Knowledge System Analysis

memory-bank 단기기억을 장기기억으로!

이 문서는 memory-bank를 단순한 대화 검색 도구가 아니라, 세션 로그를 구조화된 장기 기억으로 변환하는 지식 파이프라인으로 해석합니다. 입력 수집부터 fact 정규화, ontology 연결, MCP 기반 recall surface까지 각 레이어가 왜 분리되어 있는지와 그 설계 의도를 한 화면에 정리했습니다.

5
Core Layers
7
Flow Stages
2
Memory Models
1
Primary Goal
Framework
세 개의 큰 층
Input Layer

Archive-able Context

대화 JSONL, tool call, 세션 메타데이터, 프로젝트 경로와 브랜치 같은 실행 문맥이 memory-bank의 원재료가 됩니다.

conversation archive tool history session metadata
Transformation Layer

Searchable Knowledge

embedding, indexing, fact extraction, contradiction 처리로 로그를 검색 가능하고 재사용 가능한 구조로 바꿉니다.

sqlite-vec fact extraction consolidation
Recall Layer

Grounded Interfaces

MCP, CLI, UI, avatar가 같은 기반 지식을 서로 다른 진입점으로 노출해 회수 비용을 낮춥니다.

MCP tools CLI dashboard UI
Rationale
왜 이 구조로 나뉘는가

설계 원칙

  • Archive First원본 대화를 보존해야 요약 오류나 추출 실패가 나도 원문을 다시 해석할 수 있습니다.
  • Recall Split검색 인덱스와 fact 스토어를 분리해야 빠른 회수와 장기 지식 관리 요구를 동시에 만족시킬 수 있습니다.
  • Evolution Aware프로젝트 의사결정은 변하므로 fact revision과 contradiction 추적이 필수입니다.
  • Grounded Surfaceavatar나 graph는 생성형 요약보다 출처 있는 회수 경험을 우선합니다.

핵심 저장소

  • Archive~/.claude/projects 기반 세션 원본 보존
  • DB~/.config/superpowers/conversation-index/db.sqlite
  • Retrievalexchange rows, tool calls, vector tables
  • Knowledgefacts, revisions, ontology domains, typed relations
  • Embedding@xenova/transformers + all-MiniLM-L6-v2
Pipeline
7-Step Data Flow

Sync

src/sync.ts가 conversation JSONL을 archive로 복사하고 incremental 처리 대상을 만듭니다.

Index

src/indexer.ts가 exchange를 SQLite와 vector table에 적재해 대화 회수 기반을 만듭니다.

Search

src/search.ts가 semantic, text, hybrid 모드로 과거 대화를 다시 찾게 해줍니다.

Extract

src/fact-extractor.ts가 세션 종료 시 장기 보존 가치가 있는 사실을 추출합니다.

Consolidate

src/consolidator.ts가 중복, 충돌, 진화 이력을 정리해 fact 품질을 유지합니다.

Relate

src/ontology-classifier.ts가 domain/category를 붙이고 typed relation으로 연결합니다.

Recall

src/mcp-server.ts, CLI, UI가 search, graph, avatar 인터페이스를 제공합니다.

Map
Architecture Map

대화 로그에서 지식 인터페이스까지

Conversation Input JSONL / tool calls / metadata ~/.claude/projects Sync + Archive copy / import / summarize session history retained Index + Retrieval DB SQLite / sqlite-vec / embeddings exchange + vector tables Search Surface search / read conversation recall Fact Extraction decision / preference / pattern knowledge / constraint Fact Consolidation duplicate / contradiction evolution / revisions Ontology + Graph domain / category / relation supports / influences / supersedes MCP Tools search / read / search_facts search_ontology / ask_avatar trace_fact / explore_graph CLI Surface memory-bank sync search / show / stats index / verify / rebuild UI Surface projects / search / prompts fact browsing / exchange detail dashboard Avatar Layer grounded answer confidence cited fact sources
archive / indexing / retrieval fact lifecycle ontology / graph / avatar
Interpretation
Layer 별 해석

MCP Tool Surface

  • search는 archived conversation을 semantic, text, hybrid 방식으로 탐색합니다.
  • read는 줄 단위 범위를 열어 원문과 문맥을 직접 확인하게 합니다.
  • search_facts는 정규화된 long-term fact만 빠르게 질의합니다.
  • search_ontology, trace_fact, explore_graph는 기억을 구조 단위로 순회하게 만듭니다.

설계상 중요한 해석

  • Retrieval First모든 고차 기능은 먼저 과거 대화를 다시 찾을 수 있어야 성립합니다.
  • Fact Promotion유의미한 세션 내용을 reusable statement로 승격해야 기억 효율이 생깁니다.
  • Scoped Memory프로젝트 로컬 지식과 글로벌 패턴을 분리해 오염을 줄입니다.
  • Graph Utility사실 간 관계를 붙여야 단순 검색을 넘어 탐색과 설명이 가능해집니다.

핵심 Layer Reading

  • Archive원본 보존과 세션 단위 추적을 담당합니다.
  • Retrieval대화 재탐색과 근거 확인에 최적화됩니다.
  • Fact결정, 선호, 패턴, 제약을 reusable knowledge로 압축합니다.
  • Surface검색, 읽기, 설명, 시각화를 실제 사용자 경험으로 전달합니다.

한 줄 결론

memory-bank의 핵심은 대화를 저장하는 것이 아니라, 대화를 다시 사용할 수 있는 지식 구조로 변환하는 데 있습니다. 그래서 archive, retrieval, fact, ontology, recall surface가 순차적으로 분리되어 있고, 이 분리는 검색 성능, 지식 품질, 설명 가능성, 프로젝트 스코프 제어를 동시에 만족시키기 위한 구조적 선택으로 읽는 편이 맞습니다.

Related
Connected Pages

Docs Index

홈으로 돌아가 다른 Deep Dive 문서와 함께 탐색합니다.

/init-project 상세 분석

장기 지식 축적이 실제 프로젝트 분석 파이프라인과 어떻게 연결되는지 이어서 볼 수 있습니다.

memory-bank Repository

실제 구현 저장소에서 CLI, MCP, fact graph 계층을 코드 단위로 확인합니다.