Context Vault

Synaptic Memory - 뇌 영감 지식 그래프 라이브러리

11 min read

Synaptic Memory 리서치

GitHub: https://github.com/PlateerLab/synaptic-memory 조사일: 2026-03-23

프로젝트 개요 및 목적

Synaptic Memory는 LLM 에이전트와 멀티 에이전트 시스템을 위한 뇌 영감 지식 그래프(Brain-inspired Knowledge Graph) 라이브러리 + MCP 서버다.

핵심 문제 의식

LLM 에이전트는 기억하지 못한다. 같은 실수를 반복하고, 과거의 성공 사례를 활용하지 못하며, 팀이 축적한 지식에 접근할 수 없다.

기존 RAG는 “문서를 청크로 쪼개 벡터로 검색”하는 수준에 그치지만, 에이전트는 더 구조화된 경험이 필요하다:

  • “이 상황에서 지난번에 어떤 결정을 내렸고, 결과는 어떠했나?”
  • “이 패턴이 이전에 실패한 적 있나? 왜?”
  • “이 툴을 쓸 때 어떤 규칙을 따라야 하나?”

해법: 뇌의 작동 방식을 차용한 4가지 원리로 에이전트 메모리 구현

주요 기능

1. Spreading Activation (연상 검색)

뇌가 “배포”를 들으면 CI/CD, 롤백, 인시던트, 모니터링을 함께 활성화하듯, 검색어와 연관된 노드들을 그래프 탐색으로 함께 활성화한다.

검색: "deployment"
  → FTS 매칭: [CI/CD pipeline, deployment automation]
  → 이웃 노드 활성화: [rollback strategy, canary deployment, incident response rules]
  → 공명 랭킹: relevance × importance × recency × vitality × context

2. Hebbian Learning (“함께 발화하는 것은 함께 연결된다”)

성공/실패 경험을 엣지 가중치로 학습:

[PostgreSQL 선택] + [벡터 검색 구현] → 성공
  → edge weight += 0.1 → 향후 검색에서 함께 활성화

[테스트 생략] + [프로덕션 배포] → 실패
  → edge weight -= 0.15 → 실패 경험이 먼저 노출

3. Memory Consolidation (4단계 메모리 생명주기)

단계보존 기간진급 조건
L0 (Raw)72시간-
L1 (Sprint)90일접근 3회 이상
L2 (Monthly)1년접근 10회 이상
L3 (Permanent)영구성공률 80%+ (60% 미만 시 강등)

4. Auto-Ontology (자동 온톨로지 구성)

“에이전트가 언제 이 지식을 검색할까?”를 예측하여 메타데이터를 자동 생성:

await graph.add("결제 장애 포스트모템", "PG API 타임아웃 발생...")
 
# LLM이 자동 생성:
# kind: LESSON
# tags: ["payment", "PG", "timeout", "circuit-breaker"]
# search_keywords: ["결제 실패 원인", "PG 장애 대응", "API 타임아웃 해결"]
# search_scenarios: ["결제 시스템 장애 시 과거 사례 검색"]
# 기존 노드와 관계: --[LEARNED_FROM]--> "배포 결정"

5. 5축 공명 스코어링

Score = 0.55 × relevance     검색 매칭 점수
      + 0.15 × importance    (성공 - 실패) / 접근 횟수
      + 0.20 × recency       exp(-0.05 × 업데이트_이후_일수)
      + 0.10 × vitality      주기적 감쇠 ×0.95
      + (context weight) × context  세션 태그 Jaccard 유사도

검색 의도에 따라 가중치가 달라진다. 같은 쿼리도 의도가 다르면 다른 결과가 나온다.

6. MCP Server — 16개 툴

synaptic-mcp                              # stdio (Claude Code 연결)
synaptic-mcp --db ./knowledge.db          # SQLite 백엔드
synaptic-mcp --embed-url http://...       # + 자동 임베딩
  • Knowledge (7개): knowledge_search, knowledge_add, knowledge_link, knowledge_reinforce, knowledge_stats, knowledge_export, knowledge_consolidate
  • Agent Workflow (4개): agent_start_session, agent_log_action, agent_record_decision, agent_record_outcome
  • Semantic Search (3개): agent_find_similar, agent_get_reasoning_chain, agent_explore_context
  • Ontology (2개): ontology_define_type, ontology_query_schema

기술 스택

언어 및 런타임

  • Python (메인 언어)
  • uv (패키지 매니저)

지원 백엔드

백엔드그래프 탐색벡터 검색규모용도
MemoryBackendPython BFS코사인~10K테스트
SQLiteBackendCTE 재귀-~100K임베디드
PostgreSQLBackendCTE 재귀pgvector HNSW~1M프로덕션
Neo4jBackendCypher 네이티브-~10B대규모 그래프
QdrantBackend-HNSW + 양자화~10B벡터 전용
MinIOBackend--~10TBBlob (S3 호환)
CompositeBackendNeo4jQdrant무제한통합 라우터

임베딩 / LLM 프로바이더

  • Ollama (로컬)
  • vLLM (로컬)
  • OpenAI 호환 API

온톨로지 구성 방식

모드설정비용
Rule-basedRuleBasedClassifier()무료 (키워드 매칭)
+ EmbeddingRuleBasedRelationDetector() + 임베더무료 (로컬)
+ LLMLLMClassifier() + LLMRelationDetector()로컬/API

CI/CD

  • GitHub Actions (CI 뱃지 확인됨)
  • PyPI 배포 자동화

파일 구조

PlateerLab/synaptic-memory/
├── .github/              # GitHub Actions CI 설정
├── src/                  # 메인 소스 코드
├── tests/                # 테스트 (266개+ 테스트 포함)
├── docs/                 # 문서
├── docker-compose.yml    # 개발 환경 (Neo4j, Qdrant, MinIO)
├── pyproject.toml        # 패키지 설정 및 의존성
├── uv.lock               # 의존성 잠금 파일 (398KB)
├── CLAUDE.md             # Claude Code 전용 지침
├── CHANGELOG.md          # 변경 이력
├── CONTRIBUTING.md       # 기여 가이드
└── README.md             # 프로젝트 문서

내부 아키텍처 (SynapticGraph Facade)

SynapticGraph (Facade)
  ├── Auto-Ontology ───── RuleBasedClassifier / LLMClassifier
  │                       RuleBasedRelationDetector / LLMRelationDetector
  ├── OntologyRegistry ── 타입 계층 + 속성 상속 + 제약 검증
  ├── ActivityTracker ─── 세션 / 툴 호출 / 결정 / 결과 캡처
  ├── AgentSearch ──────── 6가지 의도 기반 검색 전략
  ├── HybridSearch ─────── FTS + vector → synonym → LLM rewrite
  ├── ResonanceScorer ──── 5축 공명 (relevance × importance × recency × vitality × context)
  ├── HebbianEngine ────── 공동 활성화 강화/약화
  ├── ConsolidationCascade  L0→L3 생명주기
  ├── EmbeddingProvider ── 자동 벡터 생성 (Ollama/vLLM/OpenAI)
  ├── LLMProvider ──────── 온톨로지 구성용 LLM (Ollama/OpenAI)
  └── Exporters ─────────── Markdown, JSON
       │
  StorageBackend (Protocol)
       │
  MemoryBackend / SQLiteBackend / PostgreSQLBackend / Neo4jBackend / CompositeBackend

기본 온톨로지 타입

knowledge                          agent_activity
  ├── concept                        ├── session
  ├── entity                         ├── tool_call
  ├── lesson                         ├── observation
  ├── decision                       ├── reasoning
  ├── rule                           └── outcome
  └── artifact

설치 및 사용 방법

설치

pip install synaptic-memory                      # Core (zero deps)
pip install synaptic-memory[embedding]           # + 자동 임베딩 (Ollama/vLLM)
pip install synaptic-memory[sqlite]              # + SQLite FTS5
pip install synaptic-memory[scale]               # Neo4j + Qdrant + MinIO + embedding
pip install synaptic-memory[mcp]                 # + MCP 서버
pip install synaptic-memory[all]                 # 전체

사용 패턴별 예시

1. 인메모리 — 의존성 없이 즉시 시작

from synaptic import SynapticGraph, ActivityTracker
 
graph = SynapticGraph.memory()
tracker = ActivityTracker(graph)
 
result = await graph.agent_search("DB 마이그레이션 실패")
 
session = await tracker.start_session(agent_id="my-agent")
decision = await tracker.record_decision(
    session.id,
    title="PostgreSQL 선택",
    rationale="벡터 검색 + ACID 필요",
    alternatives=["MongoDB", "SQLite"],
)
await tracker.record_outcome(
    decision.id,
    title="마이그레이션 성공",
    content="무중단 배포 달성",
    success=True,
)

2. SQLite — 가벼운 프로덕션

graph = SynapticGraph.sqlite("knowledge.db")
await graph.backend.connect()
 
# kind와 관계가 자동 분류됨
await graph.add("환불 정책", "7일 이내 환불 가능...")  # → kind=RULE (자동)

3. Full — LLM 분류 + 임베딩 + 관계 감지

from synaptic import SynapticGraph
from synaptic.backends.sqlite import SQLiteBackend
from synaptic.extensions.llm_provider import OllamaLLMProvider
 
graph = SynapticGraph.full(
    SQLiteBackend("knowledge.db"),
    llm=OllamaLLMProvider(model="qwen3:0.6b"),
    embed_api_base="http://localhost:8080/v1",
    embed_model="BAAI/bge-m3",
)

4. Scale — CompositeBackend (Neo4j + Qdrant + MinIO)

composite = CompositeBackend(
    graph=Neo4jBackend("bolt://localhost:7687"),
    vector=QdrantBackend("http://localhost:6333"),
    blob=MinIOBackend("localhost:9000", ...),
)
graph = SynapticGraph.full(composite, embed_api_base="...")
# 내부 라우팅: embedding → Qdrant, 100KB+ → MinIO, 나머지 → Neo4j

MCP 서버 실행

synaptic-mcp                               # Claude Code에서 stdio로 연결
synaptic-mcp --db ./knowledge.db           # SQLite 백엔드

개발 환경

uv sync --extra dev --extra sqlite --extra neo4j --extra qdrant --extra minio
uv run pytest -v                           # 266개+ 테스트
uv run pytest tests/benchmark/ -v -s      # 벤치마크 (8개 데이터셋 + 어블레이션)
uv run ruff check --fix && uv run ruff format

특이사항 / 인사이트

경쟁 프로젝트 대비 차별점

기능Synaptic MemoryCogneeMem0LightRAG
에이전트 경험 학습Hebbian 공동활성화---
메모리 통합 (4단계)L0→L1→L2→L3-부분-
자동 온톨로지규칙+LLM+임베딩LLM만-LLM만
다축 랭킹5축 공명---
Zero-dep 코어Pure Python---
MCP 서버16개 툴---
한국어 최적화FTS + 동의어 튜닝--

2026-04-07-memory-layer-comparison-honcho-mem0-supermemory — AI 에이전트 메모리 레이어 3-Way 성능 비교 (2026.4)

한국어 최적화 명시

한국어 FTS + 동의어 튜닝이 공식 지원된다는 점이 주목할 만하다. 한국어 QA 벤치마크(KLUE-MRC)도 포함되어 있다.

벤치마크 결과 (FTS만, 임베딩 없이)

데이터셋코퍼스MRRnDCG@10R@10
Allganize RAG-Eval (금융/의료/법률)3000.7930.8100.870
HotPotQA-24 (멀티홉)2260.7540.6360.729
AutoRAGRetrieval (엔터프라이즈)7200.6390.6770.800
KLUE-MRC (한국어 QA)5000.6070.6430.760

Hermes Multi-Agent 연동 가능성

  • MCP 서버(16개 툴)를 통해 Hermes Agent와 직접 연동 가능
  • synaptic-mcp --db ./knowledge.db 실행 후 Claude Code / Hermes Agent에서 MCP로 연결
  • 에이전트가 경험(툴 호출, 결정, 결과)을 자동으로 지식 그래프에 기록하고, 향후 검색에 활용 가능
  • SQLite 백엔드는 Docker 볼륨으로 에이전트별 격리 가능

설계 철학상 특이점

  • Zero-dependency 코어: pip install synaptic-memory 만으로 인메모리 모드 즉시 사용 가능
  • Factory method 패턴: .memory(), .sqlite(), .full() 팩토리로 복잡성을 숨기면서 커스텀 조합도 허용
  • 의도 기반 검색: 같은 쿼리도 6가지 의도(past_failures, context_explore 등)에 따라 다른 가중치 적용
  • CLAUDE.md 포함: 저장소 자체에 Claude Code 전용 지침 파일이 있음 — Claude와의 협업을 명시적으로 고려

저장소 통계

항목값
저장소PlateerLab/synaptic-memory
설명Brain-inspired knowledge graph: spreading activation, Hebbian learning, memory consolidation.
생성일2026-03-21
최종 업데이트2026-03-22
Stars8
Forks0
Open Issues5
Watchers0
주요 언어Python
저장소 크기~11.7 MB
라이선스MIT
기본 브랜치main
접근성Public

토픽 태그

ai-agent embedding graph-database hebbian-learning knowledge-graph llm mcp mcp-server memory multi-agent neo4j ontology postgresql python qdrant rag retrieval-augmented-generation semantic-search sqlite vector-search

그래프 뷰