아키텍처

<!-- translations:start -->

English · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Tesserae는 컨텍스트 엔진입니다. 프로젝트로부터 자기 개선 지식 베이스를 재구축하고 이를 바로 쓸 수 있는 컨텍스트로 에이전트에게 건네줍니다. 세 개의 기둥 위에서 동작합니다: (1) 세션 모니터링 — 라이브 에이전트/작업 세션을 감시하고 발견 사항을 발생하는 대로 포착; (2) 자율적·능동적 지식 수집 — 지시를 기다리는 대신 지식을 지속적으로 끌어오고 재추출하여 베이스를 개선하는 파이프라인 + 슈퍼바이저 루프; (3) 온디맨드 문서/컨텍스트 — 같은 베이스에서 컴파일되는 사용자 요청 아티팩트. 타입 그래프, markdown vault, 정적 사이트는 지식 베이스의 *프로젝션*이고; 엔진은 그것들을 신선하게 유지하며 에이전트에게 공급하는 루프입니다.

그 아래에서 Tesserae는 소스 자료 디렉터리를 통제된 타입 지식 그래프로 바꾸고, 그 그래프를 내구성 있는 markdown 위키 레이어를 거쳐 정적이고 AI 친화적인 웹사이트로 프로젝션합니다. 2026년 4월 리디자인은 프로젝션 쪽을 Karpathy 3레이어 모델 중심으로 재조직했습니다: 원시 증거는 원시 그대로 유지되고, 타입 그래프가 온톨로지를 통제하며, markdown 위키 레이어가 그래프와 모든 렌더링 출력 사이에 자리합니다. 정적 사이트는 그래프의 직접 덤프가 아니라 그 위키 레이어의 *렌더러*이며, 스키마는 MD0의 통제 온톨로지입니다. v0.5.0 마일스톤(2026년 6월)은 세 기둥 모두를 구동하는 엔진 스파인을 추가했습니다 — 아래의 *엔진 스파인*과 *온디맨드 컨텍스트 컴파일러*를 참조하세요.

Karpathy 3레이어 모델

LLM 친화적 지식 베이스에 대한 Andrej Karpathy의 프레이밍은 각각 고유한 내구성 보장을 갖는 세 레이어를 구별합니다:

스키마는 별도의 축으로 세 레이어 모두를 가로지릅니다: graph.json의 ResearchGraph는 L2 페이지가 링크하는 통제 온톨로지이고, MD2의 ResearchNodeType / 엣지 화이트리스트가 어떤 타입이 존재할 수 있는지에 대한 진실의 원천입니다.

리디자인은 L2를 명시적으로 추가했습니다. 2026년 4월 이전에는 정적 사이트가 graph.json에서 곧바로 프로젝션되었고; 위키 레이어는 Obsidian vault export 안에만 존재했습니다. 이를 분리해서 얻은 것:

• 단일한 인간 편집 가능 표면 (Obsidian이나 아무 markdown 에디터에서 .tesserae/wiki/를 열기).
• 멱등 재빌드: project compile을 재실행해도 소스 콘텐츠가 바뀌지 않았다면 파일 diff가 0.
• 진화 로그: synthesis 페이지가 시간에 걸쳐 축적되어 프로젝트가 스스로를 서술하게 함.

파이프라인

data/, docs/, src/                                    (L1 raw)
        │
        ▼  project compile  (tesserae/project.py)
┌───────────────────────────┐
│ ResearchGraphExtractor    │   deterministic + selective Claude
│ + canonicalization        │
└───────────┬───────────────┘
            │
            ▼
┌───────────────────────────┐
│ ResearchGraph (graph.json)│   schema: research_graph.py
└───────────┬───────────────┘
            │
            ├──▶ WikiLayerProjector   (one page per L1/L2 node)
            ├──▶ SynthesisProjector   (pulse, daily, weekly, topic, …)
            │
            ▼
┌───────────────────────────┐
│ .tesserae/wiki/  (L2 md)  │   sources/, concepts/, entities/,
│                            │   papers/, repos/, topics/,
│                            │   syntheses/, questions/
└───────────┬───────────────┘
            │
            ▼  StaticSiteBuilder.write_site
┌───────────────────────────┐
│ .tesserae/site/  (L3 html)│   index.html, <kind>/index.html,
│                            │   <kind>/<slug>.html,
│                            │   per-page .txt + .json siblings,
│                            │   llms.txt, llms-full.txt,
│                            │   graph.json, graph.jsonld,
│                            │   search-index.json,
│                            │   sitemap.xml, rss.xml,
│                            │   robots.txt, ai-readme.md,
│                            │   manifest.json
└───────────────────────────┘

모든 단계는 증분적입니다. 그래프 추출기는 manifest.json 콘텐츠 해시를 사용해 변경되지 않은 소스 파일을 건너뜁니다. WikiPageStore.write_page는 본문 해시가 디스크에 이미 있는 것과 일치하면 False를 반환하고 쓰기를 건너뜁니다. StaticSiteBuilder는 .tesserae/site/를 삭제하고 재기록하지만 출력은 결정적입니다 — 아래 "멱등성 이야기"를 참조하세요.

컨텍스트 컴파일러 데이터플로

온디맨드 컨텍스트 컴파일러(MD0)는 기둥 3의 헤드라인 경로입니다. 질의 그리고/또는 명시적 시드 노드 id가 주어지면, compile_context는 그래프에서 곧바로 맞춤형 citation markdown 번들을 빌드해 메모리로 반환합니다 — .tesserae/ 아래에 아무것도 기록하지 않습니다.

query / seeds
     │
     ▼  1. Seed resolution
        explicit seeds (kept iff they exist) + hybrid_search() hits, deduped, stable order
     │
     ▼  2. PPR expansion
        retrieval.ppr.personalized_pagerank ranks the depth-bounded k-hop neighbourhood;
        empty result (disconnected seeds) → fall back to seed order (bundle is never empty)
     │
     ▼  3. Budget-bound selection
        walk PPR order, include each node's cited body until the next would overflow
        `budget` chars (budget <= 0 = uncapped; over-budget marker on a word boundary)
     │
     ▼  4. Cited markdown assembly
        one section per selected node + a trailing `## Citations` block.
        Body text prefers the projected wiki page (when a store + public wiki kind exist),
        else the node description, else a minimal stub. The no-LLM body embeds NO
        wall-clock timestamp → byte-identical for the same (graph, query, seeds, depth, budget).
     │
     ▼  5. Optional LLM synthesis  (only when synthesize=true AND ANTHROPIC_API_KEY is set)
     ▼
   ContextBundle { query, seeds_used, ranked_nodes, selected_nodes,
                   citations[ContextCitation], body, synthesized,
                   char_budget_used, char_budget_total }

기본값: depth=2, budget=32000. 결정적 조립(1–4단계)이 계약이고; LLM 합성은 순수하게 부가적입니다. 같은 파이프라인이 project context CLI 명령, compile_context MCP 도구, 토픽 범위 export 슬라이스(slice_export_context_for_topic, 토픽 범위 llms.txt)를 뒷받침합니다.

모듈 맵

위키 + synthesis (L2)

그래프 + 온톨로지

사이트 렌더러 (L3)

파이프라인 오케스트레이션

엔진 스파인 (v0.5.0 — 기둥 1 & 2)

엔진 스파인은 세션 모니터링과 자율 재수집을 구동하는 프로세스 내 루프입니다. 같은 Pipeline.run()이 CLI, 슈퍼바이저 데몬, 그리고 (이후) MCP 서버가 모두 호출하는 단일 refresh 경로입니다.

자기 개선 메모리 (v0.5.0 — 기둥 2)

Phase 5가 영속적 자기 개선을 활성화했습니다. 가변적인 노드별 상태는 node_memory SQLite 사이드카(.tesserae/sqlite.db 내부)에 존재하며, 불변의 node_provenance.first_seen_at 최초 관측 스탬프(Phase 4 사이드카)와 분리되어 있습니다. compile이 그래프 위에서 결정적 패스 집합을 구동합니다.

재발 신뢰도는 출력에서 수치입니다: temporal 프로젝션은 각 fact의 confidence를 NodeMemoryRow.confidence(SQLite에서는 텍스트, temporal.py를 통해 노출)로부터 각인하고, 저장된 값이 없을 때만 infer_confidence로 폴백합니다.

Retrieval (v0.5.0 — 기둥 2 & 3)

온디맨드 컨텍스트 컴파일러 (v0.5.0 — 기둥 3 헤드라인)

영속화 포트 + 그래프 저장소

외부 어댑터 (이번 라운드에서 변경 없음)

프로젝트 워크스페이스 레이아웃

.tesserae/
  config.json                 project name, source kind, source list
  graph.json                  validated ResearchGraph (incl. Synthesis nodes)
  manifest.json               per-source content hashes (input dedup)
  sqlite.db                   SQLite graph store; also owns the node_provenance
                              (first-seen, Phase 4) and node_memory (decay /
                              confidence / superseded, Phase 5) sidecar tables
  temporal_facts.jsonl        Graphiti-style temporal projection (numeric recurrence confidence)
  graphiti_episodes.jsonl     dependency-free Graphiti episode export
  report.md                   graph quality / summary
  competitive_report.md       comparison vs. MegaMem / Graphiti / others
  markdown_projection/        flat human-readable markdown
  obsidian_vault/             Obsidian projection w/ .obsidian/, raw/assets/
  agent_harness/              Claude Code / Codex / etc. harness files
  harness_sessions/           imported local Claude Code/Codex sessions
  wiki/                       L2 markdown wiki — see below
  site/                       L3 static site — see below

.tesserae/wiki/ (L2)

wiki/
  sources/<slug>.md           raw documents from data/ + docs/, with frontmatter
  concepts/<slug>.md          Concept / TechnicalTerm / Algorithm / etc.
  entities/<slug>.md          Model / Dataset / Benchmark / Metric / Org / Person
  papers/<slug>.md            Paper hub
  repos/<slug>.md             Repository / Project / CodeProject
  topics/<slug>.md            ResearchField / ResearchTopic / ApproachFamily / Trend
  syntheses/<slug>.md         pulse, daily_digest, weekly, topic, comparison, field_overview
  questions/<slug>.md         OpenQuestion

각 파일은 손으로 편집할 수 있습니다; 본문 해시가 프로젝터가 기록할 내용과 다르기만 하면 다음 compile이 사용자 편집을 존중합니다. (본문만 편집하면 이깁니다; frontmatter 편집은 frontmatter가 재생성되기 때문에 다음 compile에서 집니다.) Obsidian 사용자는 .tesserae/wiki/를 직접 열 수 있습니다; 기존 obsidian_vault/ 어댑터는 별도의 프로젝션이지 대체물이 아닙니다.

.tesserae/site/ (L3)

site/
  index.html                  home + project pulse
  about.html                  schema, build info
  assets/{style.css,app.js}   single CSS bundle + single JS bundle
  sources/index.html
  sources/<slug>.html
  sources/<slug>.txt          AI sibling — plain text
  sources/<slug>.json         AI sibling — structured record
  concepts/…  entities/…  papers/…  repos/…  topics/…  syntheses/…  questions/…
  sessions/index.html          imported harness-session index
  sessions/<project>/<id>.html session detail: summary, metadata, turn rail, markdown turns, collapsed tools
  timeline/index.html
  graph/index.html            interactive 2D + 3D force layout
  graph.json                  full graph payload (incl. code nodes, for tooling)
  graph.jsonld                schema.org Dataset, wiki-layer nodes only
  search-index.json           palette + page search; wiki-layer kinds only
  llms.txt                    llmstxt.org — short index
  llms-full.txt               llmstxt.org — every page body, capped 5MB
  sitemap.xml                 every emitted route
  rss.xml                     last 30 syntheses
  robots.txt                  permissive (crawl + index)
  ai-readme.md                machine-readable site map
  manifest.json               sha256 + size for every emitted file

의도적으로 제외된 것

리디자인은 명시적인 선을 그었습니다: 코드 클래스와 코드 함수 노드는 graph.json에 남지만(따라서 MCP와 Graphiti 소비자는 여전히 볼 수 있음) HTML 페이지를 절대 얻지 않고, search-index.json에 절대 나타나지 않으며, 내비게이션에도 절대 나타나지 않습니다. 그것이 사용자 대상 계약입니다 — 위키는 문서 우선 지식 베이스이지 함수 브라우저가 아닙니다.

구체적으로, StaticSiteBuilder는 타입이 L2 위키 종류 맵(tesserae/wiki_projector.py::_KIND_FOR_TYPE)에 없는 모든 노드를 건너뜁니다:

• L2 + L3에서 제외: CodeClass, CodeFunction, CodeModule, Dependency, EvidenceSpan, SourceFile, 모든 Claim 변형(Claim, ContributionClaim, PerformanceClaim, ComparisonClaim, LimitationClaim, CausalClaim).
• 여전히 나타나는 표면: 관련 위키 페이지의 불릿, 배지, 이웃 수, 인라인 근거 발췌, 그리고 다운스트림 도구를 위한 graph.json.

코드 수준 탐색이 필요하면 소스 트리에 LSP / call-graph 도구를 직접 대세요 — 그것은 "이 프로젝트가 아는 것의 위키"와는 다른 문제입니다.

멱등성 이야기

리디자인은 변경되지 않은 입력에 대해 연속된 두 번의 project compile 실행이 바이트 단위로 동일한 출력을 목표로 합니다. 구성 요소:

1. 소스 추출은 manifest.json 콘텐츠 해시를 사용합니다; 변경되지 않은 파일은 건너뛰므로 그래프가 안정적으로 유지됩니다.
2. 위키 레이어 쓰기는 본문 수준에서 멱등적입니다. WikiPageStore.write_page는 기존 파일을 읽고, frontmatter를 벗겨내고, 본문을 sha256 해싱하고, 새 본문이 같은 해시라면 — 새 frontmatter의 generated_at timestamp가 다르더라도 — 바로 반환합니다. 이것이 재빌드에서 git diff를 좁게 유지하는 핵심 트릭입니다.
3. Synthesis 출력은 frontmatter에 content_hash: sha256-…를 담습니다. 본문 해시는 generated_at 없이 계산되므로 같은 그래프에서 반복 compile해도 같은 해시가 나오고, Synthesis 노드는 그래프 메타데이터에 같은 content_hash를 담습니다.
4. 사이트 렌더링은 write_site 시작 시 site/를 삭제한 뒤 결정적으로 기록합니다: 라우트는 정렬되고, 딕셔너리는 sort_keys=True로 덤프되며, manifest.json은 sorted(rglob("*"))로 순회됩니다. 두 실행이 manifest를 포함해 바이트 단위로 동일한 파일을 생산합니다.

이는 tests/test_site_pages.py와 tests/test_project_e2e_redesign.py의 엔드투엔드 스모크(두 번 compile, 사이트 diff, 파일 델타 0 기대)로 검증됩니다.

스케일링 참고 사항

• 그래프 뷰 노드 상한. MD0이 인터랙티브 포스 레이아웃의 페이지 내장 페이로드를 제한합니다. 약 1500 노드를 넘으면 중급 하드웨어에서 브라우저 측 시뮬레이션이 느려지므로, 개수가 상한을 넘으면 페이지는 차수가 가장 낮은 위키 레이어 노드부터 버립니다. 내보낸 graph.json은 영향받지 않습니다 — 항상 전체 그래프를 담습니다. 코드 노드는 상한 적용 전에 필터링됩니다.
• llms-full.txt 상한. MD1에 5 MB 안전 상한이 적용됩니다; 상한에 도달하면 파일은 [TRUNCATED — see graph.jsonld for the full set] 마커로 끝납니다. JSON-LD 소비자는 전체 집합을 기대하므로 graph.jsonld는 무제한입니다.
• 검색 인덱스. 위키 레이어 종류만. 코드 그래프 노드는 search-index.json에 절대 들어가지 않습니다; 리디자인 목표는 dogfood 코퍼스 기준 500 KB 미만이며 오늘 우리는 그보다 훨씬 아래에 있습니다.
• 페이지별 바이트 예산 (경험칙). 각 상세 페이지 < 60 KB gz HTML, 공유 CSS < 30 KB, 공유 JS < 25 KB, sigma 벤더는 그래프 페이지에서만(~60 KB). 그래프 뷰는 한 번 로드되는 3D-force-graph + Three.js를 사용하고; 나머지 모든 페이지는 vanilla로 유지됩니다.
• dogfood에서의 compile 시간. 최신 개발 머신에서 ~300개의 markdown 파일이 5초 미만에 추출됩니다; 사이트 렌더가 ~2초를 추가합니다. 위키 레이어의 멱등성 덕분에 이후 compile은 변경된 경로만 건드립니다.

프론트엔드 인터랙션 표면

• 검색 팔레트 — cmd+k / ctrl+k / /. 위키 종류로 범위 한정된 search-index.json에 대한 퍼지 매치. 최근 페이지는 localStorage에 영속화.
• 테마 토글 — 우상단 버튼; data-theme="dark"가 localStorage에 저장되고 플래시를 피하기 위해 페인트 전에 적용됨.
• 고정 오른쪽 TOC — 데스크톱 전용; 모바일에서는 <details> 드로어로 접힘. 페이지 본문의 <h2> / <h3>에서 생성.
• 활동 히트맵 — 월 + 요일 레이블이 있는 26주 SVG. 셀은 그 날의 digest.md 소스 페이지가 존재하면 그리로 링크. (일자별 타임라인 상세 페이지 — /timeline/<YYYY-MM-DD>.html — 는 명시적 후속 작업; render_timeline의 인라인 알림이 이를 표시. ⚠ 진행 중.)
• 그래프 뷰 — /graph/. 호버 툴팁, 엣지 레이블, 커서 기준 줌을 갖춘 3D 포스 레이아웃(3d-force-graph + Three.js)과 2D 폴백 뷰. 노드 색상은 ResearchNodeType에서.
• 모바일 셸 — 드로어 레일, 하단 내비, 유동 타이포, 터치 안전 히트 타깃(≥ 44 px).

테스트 전략

• 단위 — tests/test_wiki_store.py, tests/test_synthesis.py, tests/test_site_components.py, tests/test_site_pages.py, tests/test_site_exports.py, tests/test_relevance.py.
• 엔진 스파인 — tests/test_pipeline.py, tests/test_refresh_pipeline.py, tests/test_daemon_core.py, tests/test_daemon_sources.py, tests/test_cli_engine.py.
• 자기 개선 메모리 — tests/test_memory_sidecar.py, tests/test_decay_supersede.py, tests/test_supersede_suppression.py, tests/test_mcp_supersede_suppression.py, tests/test_memory_contradiction_reinforce.py.
• Retrieval + embedding — tests/test_hybrid_search.py, tests/test_ppr.py, tests/test_real_embeddings_phase6.py.
• 컨텍스트 컴파일러 — tests/test_context_compiler.py(형태, citation 무결성, 결정성, 예산, PPR 폴백), tests/test_cli_context.py, tests/test_mcp_server_context.py.
• 증분 compile (실험적) — tests/test_incremental_compile.py, tests/test_incremental_parity.py, tests/test_provenance_readiness.py, tests/test_sqlite_provenance.py.
• 멱등성 — tests/test_project_e2e_redesign.py가 두 번 compile하고 wiki/와 site/의 diff가 0임을 단언.
• 링크 무결성 — tests/test_frontend.py가 방출된 모든 HTML의 href를 파싱하고 모든 내부 링크가 생성된 파일로 해석됨을 단언. nodes/codeclass-*.html은 생산되지 않음.
• AI 시블링 — 모든 path/foo.html에 대해 테스트 스위트는 path/foo.txt와 path/foo.json이 존재함을 단언; JSON은 파싱되고 {title, kind, body, links}를 포함.
• Playwright 없음 — PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 아래의 vanilla pytest.

관련 문서

• 퀵스타트 — project init에서 탐색 가능한 사이트까지의 최소 경로.
• 프론트엔드 리디자인 워크스루 — 모든 라우트의 주석 달린 투어.
• 기능 맵 — 출시된 것, 진행 중인 것, 파일 포인터 포함.
• Self-dogfood 데모 — Tesserae를 자체 저장소에 대해 실행하기.