convez.ai
MCP ServerIntegração & APIsIntermediário
PlateerLab

Synaptic Memory

PlateerLab/synaptic-memory

Grafo de conhecimento com memória para agentes LLM, zero infra, zero lock-in

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que implementa um grafo de conhecimento inspirado em neurociência, com ativação propagada, aprendizado Hebbiano e consolidação de memória. Suporta indexação de múltiplas fontes de dados (CSV, JSONL, bancos SQL, documentos Office) sem chamadas à API no momento da indexação, com busca híbrida e sincronização em tempo real via CDC.

Instalação

$npx convez-ai PlateerLab/synaptic-memory

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
33
Forks
1
Acompanhando
1
Saúde
62%
Último commit
há 4 meses
Versão
v0.16.0
Issues abertas
5
Contribuidores
1

Casos de uso

  • Construir bases de conhecimento semanticamente ricas para agentes IA explorar
  • Sincronizar grafos de conhecimento com bancos de dados em produção via CDC
  • Recuperar informação com busca híbrida (vetorial + estruturada) sem APIs externas

Veredito

Ferramenta madura e bem-documentada para quem precisa de retrieval semanticamente consciente sem dependências externas. O suporte a CDC e múltiplas fontes de dados a torna prática para ambientes empresariais, embora exija familiaridade com grafos de conhecimento e consultas estruturadas.

README

A tradução para o português deste README ainda está na fila.

Synaptic Memory

Zero API calls at index time. Zero infra. Zero lock-in. A knowledge graph + MCP tool server for LLM agents, with hybrid retrieval, CDC-based live database sync, and Korean FTS built in.

PyPI Python License

한국어 README


5-minute start

pip install "synaptic-memory[sqlite,korean,vector]"
python examples/quickstart.py

That command ingests examples/data/products.csv into a SQLite-backed graph and runs three searches — all without calling any LLM at indexing time. Full source: examples/quickstart.py.


Two calls to build a graph

import asyncio
from synaptic import SynapticGraph

async def main():
    # Any data → knowledge graph (CSV, JSONL, directory)
    graph = await SynapticGraph.from_data("./my_data/")

    # Or directly from a database — SQLite / PostgreSQL / MySQL / Oracle / MSSQL
    graph = await SynapticGraph.from_database(
        "postgresql://user:pass@host:5432/dbname"
    )

    # Live database? Use CDC mode and only re-read what changed.
    graph = await SynapticGraph.from_database(
        "postgresql://user:pass@host:5432/dbname",
        db="knowledge.db",
        mode="cdc",       # deterministic node IDs + sync state recorded
    )
    result = await graph.sync_from_database(
        "postgresql://user:pass@host:5432/dbname"
    )
    print(result.added, result.updated, result.deleted)

    # Or bring your own chunker (LangChain, Unstructured, custom OCR, ...)
    chunks = my_parser.split("manual.pdf")
    graph = await SynapticGraph.from_chunks(chunks)

    # Search
    result = await graph.search("my question", engine="evidence")

asyncio.run(main())

That's it. Auto-detects file format or DB schema, generates an ontology profile, ingests, indexes, builds FK edges.

Live database sync (CDC) — mode="cdc" enables incremental updates: tables with an updated_at-style column are read with a watermark filter, others fall back to per-row content hashing. Deletes are detected via a TEMP TABLE LEFT JOIN; FK rewires re-link the corresponding RELATED edges. Search results are identical to a full reload (locked in by a regression test). Supports SQLite, PostgreSQL, MySQL/MariaDB.

Office files (PDF/DOCX/PPTX/XLSX/HWP) are supported through the optional xgen-doc2chunk package. Install with pip install synaptic-memory[docs] or use from_chunks() with your own parser.


What it does

Your data (CSV, JSONL, PDF/DOCX/PPTX/XLSX/HWP, SQL database)
  ↓  auto-detect format / auto-discover DB schema + FKs
  ↓  DocumentIngester (text) / TableIngester / DbIngester
  ↓
Knowledge Graph
  ├─ Documents: Category → Document → Chunk
  └─ Structured: table rows as ENTITY nodes + RELATED edges (FKs)
  ↓
42 MCP tools → LLM agent explores via graph-aware multi-turn tool use

Two jobs, nothing else:

  1. Build the graph well — cheap extraction, no LLM at index time
  2. Give the LLM good tools — the agent decides what to search

Install

# Recommended — covers every example in this README
pip install "synaptic-memory[sqlite,korean,vector,mcp]"

# Or everything, including Postgres / Kuzu / Qdrant / MinIO
pip install "synaptic-memory[all]"
pip install synaptic-memory                # Core (zero deps, in-memory only)
pip install synaptic-memory[sqlite]        # + SQLite FTS5 backend
pip install synaptic-memory[korean]        # + Kiwi morphological analyzer
pip install synaptic-memory[vector]        # + usearch HNSW index
pip install synaptic-memory[mcp]           # + MCP server for Claude
pip install synaptic-memory[embedding]     # + aiohttp for embedding APIs
pip install synaptic-memory[reranker]      # + flashrank cross-encoder
pip install synaptic-memory[postgresql]    # + asyncpg + pgvector
pip install synaptic-memory[docs]          # + xgen-doc2chunk (PDF/DOCX/PPTX/XLSX/HWP)

Quick Start

Option A: Two lines (easiest)

import asyncio
from synaptic import SynapticGraph

async def main():
    # CSV file
    graph = await SynapticGraph.from_data("products.csv")

    # JSONL documents
    graph = await SynapticGraph.from_data("documents.jsonl")

    # Entire directory (scans all CSV/JSONL)
    graph = await SynapticGraph.from_data("./my_corpus/")

    # With embedding (optional, improves semantic search)
    graph = await SynapticGraph.from_data(
        "./my_corpus/",
        embed_url="http://localhost:11434/v1",
    )

    # Search
    result = await graph.search("my question", engine="evidence")
    for activated in result.nodes[:5]:
        print(activated.node.title, activated.activation)

asyncio.run(main())

Option B: MCP server (Claude Desktop / Code)

synaptic-mcp --db my_graph.db
synaptic-mcp --db my_graph.db --embed-url http://localhost:11434/v1

Claude can now call 42 tools to explore your graph — search, ingest new files into the graph mid-conversation, and sync from a live database without dropping to a CLI.

A ready-to-paste claude_desktop_config.json snippet is in examples/mcp_claude_desktop.json.

Option BX: LangChain retriever (drop-in)

pip install "synaptic-memory[sqlite,korean,vector,langchain]"
import asyncio
from synaptic import SynapticGraph
from synaptic.integrations.langchain import SynapticRetriever

async def main():
    graph = await SynapticGraph.from_data("./docs/")
    retriever = SynapticRetriever(graph=graph, k=5, engine="evidence")

    docs = await retriever.ainvoke("my question")
    for doc in docs:
        print(doc.page_content[:80], "   ", doc.metadata["score"])

asyncio.run(main())

Runnable example: examples/langchain_retriever.py. Each hit becomes a LangChain Document with the node id, title, score, and any structured properties in metadata — works unmodified in RetrievalQA chains, agents, and RAG graphs.

Option C: Full control

import asyncio
from synaptic.backends.sqlite_graph import SqliteGraphBackend
from synaptic.extensions.domain_profile import DomainProfile
from synaptic.extensions.document_ingester import DocumentIngester, JsonlDocumentSource

async def main():
    profile = DomainProfile.load("my_profile.toml")
    backend = SqliteGraphBackend("graph.db")
    await backend.connect()

    source = JsonlDocumentSource("docs.jsonl", "chunks.jsonl")
    ingester = DocumentIngester(profile=profile, backend=backend)
    await ingester.ingest(source)

asyncio.run(main())

Option D: relation ontology (multi-hop)

When your documents cite each other by a canonical identifier — statute article numbers, standard clause codes, manual section ids — Synaptic turns those citations into REFERENCES graph edges so the agent can follow them. Still zero LLM at index time — it is rule-based extraction, auto-derived from your corpus's own identifier values.

from synaptic import SynapticGraph
from synaptic.extensions.domain_profile import DomainProfile

# Each document carries its identifier in an `article_no` property,
# scoped by `law`. That is all the configuration needed.
graph = await SynapticGraph.from_data(
    "./statutes.jsonl",
    profile=DomainProfile.with_references(
        key_property="article_no", scope_property="law"
    ),
)

The linker is self-gating: if the corpus has no clean identifier inventory it writes nothing (no-op), so this is safe to leave on. Measured impact — on a financial-statute multi-hop corpus, retrieval goes from 32% (standard dense RAG) / 31% (HippoRAG2) to 73% (synaptic) — 2.3× the nearest competitor: docs/REPORT-rag-vs-synaptic.md.

Requirement: each document must carry the identifier as a node property. Structured input (JSONL with properties) provides it directly; raw text files do not — relation linking needs identifiers.


Indexing cost comparison

ApproachLLM at indexingTrade-off
GraphRAG-style (MS GraphRAG, Cognee, Graphiti)LLM extracts entities + relations + community summariesHighest recall on narrative corpora, but every new document costs LLM tokens
LightRAG-styleLLM deferred to query timeLess index cost, but each query pays
SynapticNone. Structural + statistical signals (FK, NEXT_CHUNK, phrase DF hubs, MENTIONS) + rule-based REFERENCES edgesCheapest, deterministic; extracts explicit cross-references but won't LLM-synthesize fuzzy semantic relations

No LLM at indexing. The graph is a search index, not a knowledge base. Cross-references that documents state explicitly (statute article citations, clause codes) are turned into REFERENCES edges with zero LLM (see Option D). What Synaptic does not do is LLM-synthesize fuzzy semantic relations or community summaries — if you need those, layer them with your own agent; Synaptic gives you the primitives.

v0.16.0+: graph.search() defaults to the hybrid EvidenceSearch pipeline (BM25 + HNSW + PPR + cross-encoder + MMR). engine="legacy" still works but raises DeprecationWarning; removal is pushed to v0.18.0 to bundle with HippoRAG2-style architecture work.


Agent Tools (42 total)

Text search tools

ToolPurpose
deep_searchRecommended. Search → expand → read documents in ONE call
compare_searchAuto-decompose multi-topic queries, search in parallel
knowledge_searchCore semantic search (routes through EvidenceSearch in v0.14.2+)
agent_searchFTS + vector hybrid search with intent routing
expand1-hop graph neighbours
get_documentFull document with query-relevant chunks
search_exactLiteral substring match for IDs/codes
followWalk a specific edge type

Structured data tools

ToolPurpose
filter_nodesProperty filter (>=, <=, contains) — returns {total, showing} for accurate counting
aggregate_nodesGROUP BY + COUNT/SUM/AVG/MAX/MIN with optional WHERE pre-filter
join_relatedFK-based related record lookup — walks RELATED edges (O(degree))
top_nodesSingle-call top-N ranking — "가장 X한" / "top N" / "최대/최소" / "최근" questions without composing aggregate_nodes. Each row carries sort_value for chaining into join_related / filter_nodes(from_ids=...). v0.18-β2+.

All four structured tools emit hints on 0-result returns (alternate operator, dropped WHERE, fuzzy column match) so the agent's next turn gets a concrete corrective action instead of a retry loop.

Ingest / CDC tools (v0.14.0+)

Mid-conversation ingestion so Claude can teach itself new material without leaving the chat.

ToolPurpose
knowledge_add_documentIngest a long-text document with automatic sentence-boundary chunking
knowledge_add_tableIngest structured rows → ENTITY nodes + FK edges
knowledge_add_chunksBYO-chunker path for pre-split content
knowledge_ingest_pathIngest a CSV / JSONL / text file from the local filesystem
knowledge_removeDelete a single node with edge cascade
knowledge_sync_from_databaseIncremental sync from a live database (CDC)
knowledge_backfillRepair graphs missing embeddings or phrase hubs (v0.14.4+)

Navigation tools

ToolPurpose
list_categoriesCategory list with document counts
countStructural count by kind/category/year
session_infoMulti-turn session state

All tools return { data, hints, session }. The SearchSession tracks seen nodes across turns so the agent never re-reads the same chunk.


Retrieval Pipeline

Query
  ↓  Kiwi morphological analysis (Korean) or regex (other)
  ↓  BM25 FTS + title 3x boost + substring fallback
  ↓  Vector search (usearch HNSW, optional)
  ↓  Vector PRF (pseudo relevance feedback, 2-pass)
  ↓  PPR graph discovery (personalized pagerank)
  ↓  GraphExpander (1-hop: category siblings, chunk-next, entity mentions)
  ↓  HybridReranker (lexical + semantic + graph + structural + authority + temporal)
  ↓  MaxP document aggregation (coverage bonus)
  ↓  Cross-encoder reranker (bge-reranker-v2-m3 via TEI, optional)
  ↓  EvidenceAggregator (MMR diversity + per-doc cap + category coverage)
Result

Benchmarks

Reproducible FTS-only baseline (< 2 seconds on a laptop)

pip install "synaptic-memory[korean]"
python examples/benchmark_allganize.py

Output (deterministic, v0.16.0):

Dataset                  Corpus  Queries      MRR     R@10        Hit     Time
--------------------------------------------------------------------------------
Allganize RAG-ko            200      200    0.947    1.000   200/200     9.3s
Allganize RAG-Eval          300      300    0.911    0.950   285/300     5.9s

This is the embedder-free baseline (EvidenceSearch pipeline: BM25 + PPR + MMR, no vector index, no cross-encoder). Full source: examples/benchmark_allganize.py. Data source: allganize/RAG-Evaluation-Dataset-KO.

v0.16.0 — engine default flipped to "evidence". Combined with the v0.15.1 query-mode Kiwi improvement, FTS-only Korean retrieval moved from Allganize RAG-ko MRR 0.621 (v0.15.0) → 0.947 (v0.16.0) without any embedder or reranker. English (HotPotQA-24) 0.727 → 0.875. Full ablation: examples/ablation/run_ablation.py. Reproducibility under streaming ingest sharpens in lockstep: top-1 rank invariance rose from 54.5 % → 100 %, bit-wise top-10 identical from 51.5 % → 96 %, with MRR drift exactly zero.

RAG vs HippoRAG2 vs synaptic-memory — multi-hop retrieval (v0.25)

RAG (chunk → top-k → one LLM answer), HippoRAG2 (NeurIPS'24 LLM-entity graph + PPR), and the synaptic-memory agent measured head-to-head on the same corpus, ground truth, and strict scoring (finreg — 4,417 Korean financial-statute articles, 120 multi-hop queries):

System                        multi-hop solved
---------------------------------------------------
RAG  (FTS / BM25)                   0/120   (0%)
RAG  (dense, bge-m3)               39/120  (32%)
HippoRAG2 (LLM graph + PPR)        37/120  (31%)
synaptic-memory (agent)            88/120  (73%)

A statute article that cites another article ("제30조에 따라 …") is a multi-hop query: the cited provision shares no query vocabulary, so single-shot retrieval structurally cannot reach it. Notably, HippoRAG2 ties plain dense RAG (31% ≈ 32%) — an LLM-extracted entity graph cannot capture an exact structural citation. synaptic-memory turns cross-references into REFERENCES graph edges (StructuralReferenceLinker, LLM-free, auto-derived from the corpus) and the agent follows them — 2.3× the nearest competitor. Full report, model notes, and limits: docs/REPORT-rag-vs-synaptic.md.

Head-to-head vs Mem0 / Cognee / HippoRAG2

A runnable harness (BEIR-style corpus, same MRR / R@10 scoring code for every system):

# Synaptic only (no API keys, ~2 s)
python examples/benchmark_vs_competitors/run_comparison.py --only synaptic

# Adapters for Mem0, Cognee, HippoRAG2 ship in-tree — add them to
# --only when the respective packages are installed and API keys are set
python examples/benchmark_vs_competitors/run_comparison.py --only synaptic,mem0 --subset 10

See examples/benchmark_vs_competitors/README.md for fairness caveats. Competitor self-reported numbers (Mem0 LoCoMo 91.6, HippoRAG2 MuSiQue F1 51.9, the Zep 84→58 correction incident, etc.) are catalogued with sources in docs/comparison/published_numbers.md.

Embedder-free full-dataset summary (v0.16.0)

Run via python examples/ablation/run_ablation.py:

DatasetLangQueriesMRRHit @ 10
Allganize RAG-koko2000.947200/200
Allganize RAG-Evalko3000.911285/300
AutoRAG KOko1140.906114/114
PublicHealthQA KOko770.54664/77
HotPotQA-24 ENen240.87524/24

English multi-hop standard benchmarks (v0.16.0, subset)

Run via:

pip install "synaptic-memory[eval]"   # adds `datasets` for HuggingFace download
python examples/ablation/download_benchmarks.py
python examples/ablation/run_tier1_benchmarks.py --subset 500

Adds HotPotQA-dev (66 k corpus), MuSiQue-Ans-dev (21 k), and 2WikiMultihopQA-dev (57 k) — the three retrieval corpora the HippoRAG / GraphRAG line of research uses for head-to-head. Numbers go in docs/comparison/synaptic_results.md.

Full pipeline (BGE-M3 + cross-encoder) — v0.17.1

Measured 2026-04-19 on an H100, BAAI/bge-m3 + BAAI/bge-reranker-v2-m3 loaded in-process via transformers (no external TEI / Ollama endpoint needed):

python eval/run_all.py --quick --local-bge

14-bench single-shot (5 public + 9 private)

DatasetLangQueriesFTS-onlyFull pipelineΔ
HotPotQA-24en240.8750.979+0.104
Allganize RAG-koko2000.9470.983+0.036
Allganize RAG-Evalko3000.9110.955+0.044
PublicHealthQAko770.5470.748+0.201
AutoRAG KOko1140.9060.806−0.100 ⚠
KRRA Easyko200.9670.975+0.008
KRRA Hardko400.5830.589+0.006
KRRA Convko300.1460.166+0.020
assort Easyko150.7600.856+0.096
assort Hardko400.0000.0000
assort Convko300.4250.472+0.047
X2BEE Easyen201.0001.0000
X2BEE Harden/ko200.3790.368−0.011
X2BEE Conven/ko300.1670.164−0.003
Mean0.6150.647+0.032 (+5.2pp)

v0.17.1 is the first release where mean Full-pipeline MRR exceeds mean FTS-only MRR across all 14 benches (v0.17.0 was net −1.1 %). 12/14 benches improve or hold; the 3 mild residual regressions (X2BEE Hard / Conv, AutoRAG) are at or below single-query noise except for AutoRAG where the structural reranker mismatch persists.

When the cross-encoder helps — and when it hurts. The reranker shines on paraphrase-heavy corpora (PublicHealthQA +20 pp, HotPotQA +10 pp). On retrieval-style corpora where FTS ranking is already near-optimal (AutoRAG, X2BEE Hard) it injects noise that displaces the gold rank. v0.17.1's adaptive blend ( std/3 discriminator) and structured-row reranker skip recover most of that — AutoRAG went −0.264 → −0.100 — but pure reranker=None is the only way to hit the FTS-only ceiling on those corpora. Diagnostic: examples/ablation/diagnose_autorag.py.

Multi-turn agent (Qwen3.5-27B via vLLM, 5 turns, LLM-judge)

DatasetSingle-shotAgent solvedvs v0.13 (gpt-4o-mini)
KRRA Hard0.58930/39 (77 %)11/15 (73 %) +4 pp
assort Hard0.00030/33 (91 %)13/15 (87 %) +4 pp
X2BEE Hard0.36819/19 (100 %)17/19 (89 %) +11 pp
KRRA Conv0.16614/30 (47 %)21/30 (70 %) −23 pp
assort Conv0.47222/24 (92 %)20/24 (83 %) +9 pp
X2BEE Conv0.16425/27 (93 %)22/27 (81 %) +12 pp
Mean140/172 = 81 %

This is Synaptic's real number. Single-shot retrieval is the floor; the multi-turn agent (deep_search + compare_search + graph-context injection) brings the same questions from 0–47 % to 47–100 %. assort Hard 0/40 → 91 % under agent shows what the graph + structured tools can do that no single-shot pipeline can. 5 of 6 benches beat the v0.13 GPT-4o-mini baseline (Qwen3.5-27B upgrade). KRRA Conv regression (Qwen Korean conversational gap) is the one open issue — v0.18 track.

Known structural gap — MuSiQue (English multi-hop)

MuSiQue-Ans-dev 500q full pipeline R@5 0.453 vs HippoRAG2's published 0.747 (−0.294). Three rounds of targeted fixes (LLM query decomposition, inline phrase hub, DF-filtered entity linker) all regressed the score — the gap is structural. Closing it requires OpenIE triple extraction + query→triple dense linking, which is a v0.18.0+ research track rather than a default pipeline change. Synaptic's strength is Korean / structured-data RAG; English Wikipedia multi-hop is honestly documented as a trade-off. See docs/PLAN-v0.18-architecture.md.

Multi-turn agent (GPT-4o-mini, 5 turns max)

DatasetResult
KRRA Hard agent10-13/15 (67-87%)
X2BEE Hard agent17/19 (89%)
assort Hard agent12/15 (80%)

Structured data queries (filter / aggregate / FK join / count) work end-to-end through graph-aware tools.


Architecture

SynapticGraph.from_data("./data/")          ← Easy API
  ↓
Auto-detect → DomainProfile → Ingest → Index
  ↓
StorageBackend (Protocol)
  ├── MemoryBackend        (testing)
  ├── SqliteGraphBackend   (recommended, FTS5 + HNSW)
  ├── KuzuBackend          (embedded Cypher)
  ├── PostgreSQLBackend    (pgvector)
  └── CompositeBackend     (mix backends)
  ↓
Retrieval pipeline (BM25 + vector + PRF + PPR + reranker + MMR)
  ↓
Agent tools (42) → MCP server → LLM agent

Backends

BackendVector SearchScaleUse Case
MemoryBackendcosine~10KTesting
SqliteGraphBackendusearch HNSW~100KDefault
KuzuBackendHNSW~10MGraph-heavy
PostgreSQLBackendpgvector~1MProduction
CompositeBackendQdrantUnlimitedScale-out

Optional Extras

ExtraWhat it adds
koreanKiwi morphological analyzer for Korean FTS
vectorusearch HNSW index (100x faster vector search)
embeddingaiohttp for embedding API calls
mcpMCP server for Claude Desktop/Code
sqliteaiosqlite backend
docsxgen-doc2chunk for PDF/DOCX/PPTX/XLSX/HWP loading

Documentation

DocWhat it is
docs/GUIDE.mdFriendly intro — what/why/how, zero jargon (Korean)
docs/TUTORIAL.en.md30-minute hands-on walkthrough (English)
docs/TUTORIAL.md30-minute hands-on walkthrough (Korean)
docs/CONCEPTS.md3rd-gen GraphRAG + pipeline internals
docs/REPORT-rag-vs-synaptic.mdRAG vs synaptic-memory — measured head-to-head (multi-hop)
docs/ARCHITECTURE.mdOriginal neural-inspired design
docs/COMPARISON.mdvs GraphRAG / LightRAG / LazyGraphRAG
docs/comparison/synaptic_results.mdReproducible Synaptic numbers with provenance
docs/comparison/published_numbers.mdCompetitor self-reported numbers (with sources)
docs/paper/draft.mdarXiv preprint draft — Streaming Retrieval with Top-K Invariance
docs/paper/theorem.mdFormal theorem + proof sketch
docs/ROADMAP.mdFuture plans

Dev

uv sync --extra dev --extra sqlite --extra mcp
uv run pytest tests/ -q                   # 809+ tests
uv run ruff check --fix

License

Apache-2.0 — see LICENSE. Permits commercial use, modification, and redistribution as long as the copyright/attribution notice is preserved.

Ver o original no GitHub

Bom para

Relacionados