Author: Andrei Moldovean · conceived April 2025 · first public commit March 2026
Original concepts: shard memory architecture, HUGINN/MUNINN retrieval pipeline, NÓTT daemon, confidence decay, shard consolidation, Forgemaster orchestration.

A unified repository containing NOVA (persistent AI memory) and Forgemaster (multi-agent orchestration). NOVA is the memory layer. Forgemaster is the execution layer. They share one repo and one data store.

NOVA is a persistent memory system for AI agents. It stores conversations and decisions as modular JSON "shards" — each with metadata, confidence scores, and decay rates. A knowledge graph tracks relationships between shards so agents can retrieve contextually relevant memory, not just recent history. A parallel wiki layer holds curated, evergreen pages ingested from external sources.

NOVA runs as an MCP server, meaning any MCP-compatible client (Claude Desktop, Claude Code, Cursor) can connect to it and query/write memory using structured tool calls.

Key capabilities:

• Semantic shard retrieval via HUGINN (Haiku fast pass) + MUNINN (Sonnet deep rerank)
• Confidence-weighted recall with time-based decay
• NÓTT background daemon: decay, compaction, merge suggestions, graph sync
• Knowledge graph of inter-shard relationships with transitive BFS
• Three-tier discovery: index → summary → full shard (via summary_index.json)
• Wiki layer for curated, non-decaying knowledge
• Nidhogg ingestion pipeline with full provenance tracking
• Self-evolution loop (nova_evolve) for health-driven planning cycles
• Usage logging per operation to nova_usage.jsonl

Forgemaster is a multi-agent orchestration layer built on top of NOVA. It decomposes tasks into typed tickets and routes each to the optimal model in a defined hierarchy.

Agents run in parallel sandboxed lanes. NOVA is Forgemaster's memory backplane: every sprint reads project context from shards and writes decisions back.

Key capabilities:

• Task decomposition from design docs into typed, routable tickets
• Model routing by task type and confidence score, with complexity-keyword override
• Parallel sandboxed execution lanes
• Sprint pipeline writes implementer output to disk when the design doc names a Target file:
• Per-call JSONL event log via FORGEMASTER_EVENT_LOG
• Full NOVA integration for persistent project context across sessions

Architect (you)
    └── Lead (Sonnet)       — orchestration, review, ambiguous tickets
        └── Mid (Gemini Flash)  — bounded implementation, boilerplate, structured output
            └── Low (Haiku)     — research, documentation, fast tasks

You (design doc / feature request)
        │
        ▼
  Forgemaster Orchestrator  (Sonnet)
  ├── nova_shard_interact()    → load project context from NOVA
  ├── decompose into typed tickets
  ├── route by task type
  │       ├── architecture / review / ambiguity  → Sonnet
  │       ├── implementation / boilerplate        → Gemini Flash
  │       └── research / documentation            → Haiku
  ├── parallel lanes execute
  ├── QA pass + Lead review
  └── nova_shard_update()      → write decisions back to NOVA

cd mcp/
pip install -r requirements.txt

Copy .env.example to .env at the repo root and fill in your keys:

CLAUDE_API_KEY=sk-ant-...
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-2.5-flash
CONFIDENCE_THRESHOLD=0.65

If CLAUDE_API_KEY is absent, HUGINN and MUNINN silently fall back to local-only retrieval (token overlap + cosine over local embeddings).

claude_desktop_config.json:

{
  "mcpServers": {
    "nova": {
      "command": "python",
      "args": ["path/to/mcp/nova_server.py"],
      "env": {
        "NOVA_SHARD_DIR": "path/to/shards",
        "CLAUDE_API_KEY": "sk-ant-...",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}

python mcp/nova_server.py

NOVA-Cognition-Framework/
  mcp/
    nova_server.py           ← ACTIVE MCP server (registers all 30 tools)
    config.py                ← all env vars and defaults (single source of truth)
    schemas.py               ← Pydantic input models for core + wiki tools
    models.py                ← shared dataclasses (UsageSummary)
    store.py                 ← shard I/O, index management, summary-index layer
    graph.py                 ← knowledge graph ops (entities, relations, transitive BFS)
    maintenance.py           ← confidence decay, compaction, cosine similarity, merge
    permissions.py           ← env-driven tool gating (NOVA_DENIED_TOOLS/PREFIXES)
    hooks.py                 ← event-driven hook registry (session/post-sprint/count)
    usage.py                 ← JSONL operation logging
    session_store.py         ← session persistence (flush/load/list)
    forgemaster_runtime.py   ← sprint orchestration + real LLM dispatch
    ravens.py                ← HUGINN (Haiku) + MUNINN (Sonnet) retrieval
    nott.py                  ← NÓTT daemon: decay, compact, merge, graph sync
    nova_embeddings_local.py ← local all-MiniLM-L6-v2 embeddings + summaries
    evolve.py                ← nova_evolve self-improvement loop
    nidhogg.py               ← nidhogg_ingest/scan/status tools
    wiki.py                  ← WikiPage model, CRUD, embedding index
    wiki_ingest.py           ← wiki ingestion pipeline
    wiki_tools.py            ← nova_wiki_* MCP tools
    build_summary_index.py   ← batch-build summary_index.json via Haiku
    test_nova.py             ← memory-explorer CLI (not pytest)
    requirements.txt
    SKILL.md                 ← NOVA cognitive instructions
    ONBOARDING.md            ← fresh-install flow (used when no shards exist)
    Gemini/
      gemini_mcp.py          ← Gemini tools registered into nova_server
  utilities/
    chatgpt_to_nova.py       ← ChatGPT export migration
    shard_index.py           ← manual index rebuild
    dedup_json.py            ← duplicate shard detection
    autoresearch.py          ← automated research loop
    shard_compact.py         ← manual compaction helper
    theme_analyzer.py        ← theme distribution analysis
  shards/                    ← live shard data (never edit directly)
  wiki/                      ← curated markdown pages with YAML frontmatter + [[wikilinks]]
  intake/                    ← drop zone for nidhogg_scan
  nova_sessions/             ← flushed MCP session state
  output/                    ← built artifacts, forgemaster event logs
  forgemaster/
    AGENTS.md                ← orchestration config and model routing
    SKILL_LIBRARY.md         ← index of all skills across 15 domains
    STANDARDS.md             ← authoring standard for all forgemaster content
    skills/                  ← core orchestration skills (10 files)
    library/                 ← domain skill library (208 files, 15 categories)
    agents/                  ← agent persona definitions (326 files, 18 divisions)
  docs/                      ← reference and roadmap documents
  Donors/                    ← reference implementations
  .env                       ← API keys (never commit)
  .env.example               ← template (committed)

Relation types: influences, depends_on, contradicts, extends, references, merged_from.

Wiki pages live in wiki/ as markdown with YAML frontmatter and [[wikilinks]]. They are evergreen — they do not decay — and are only created/updated via nova_wiki_ingest.

Nidhogg is non-destructive: it appends a nidhogg block to matched shards and never rewrites existing fields. Idempotent via SHA256 manifest.

⚠ Side effect: nova_evolve runs git add and git commit locally when tests pass. On test failure it runs git checkout -- . to roll back the staged changes. Nothing is pushed to a remote. Use dry_run=true if you just want the director prompt. If mcp/ changed, it writes .sdd/runtime/restart_requested.

Registered into nova_server via mcp/Gemini/gemini_mcp.py:

Read-only resources exposed alongside the tools:

• nova://skill — contents of mcp/SKILL.md
• nova://index — current shard index JSON
• nova://graph — current knowledge graph JSON
• nova://usage — last 100 log entries + session token totals

nova_server.py is a thin MCP adapter. All business logic lives in dedicated modules:

• mcp/nova_server.py and exported MCP tools
• Core runtime modules: mcp/store.py, mcp/graph.py, mcp/maintenance.py, mcp/forgemaster_runtime.py, mcp/permissions.py, mcp/session_store.py, mcp/hooks.py
• Retrieval and indexing pipeline: mcp/ravens.py, mcp/nova_embeddings_local.py, mcp/build_summary_index.py
• Wiki and ingestion modules: mcp/wiki.py, mcp/wiki_ingest.py, mcp/wiki_tools.py, mcp/nidhogg.py

• utilities/ scripts (migration helpers, diagnostics, ad-hoc maintenance tools)
• mcp/test_nova.py memory explorer CLI
• Planning/reference docs under docs/ and donor/reference materials under Donors/
• forgemaster/library/ and forgemaster/agents/ skill/persona content

Original architecture documented before any public commit. These documents establish authorship of the core concepts:

Original named concepts in this repository: shard (memory unit), HUGINN/MUNINN (retrieval pipeline), NÓTT (maintenance daemon), confidence decay, shard consolidation, Forgemaster (orchestration layer).

• Never manually edit files in shards/ or wiki/ — always use the MCP tools
• Auto-generated files, never commit: shard_index.json, shard_graph.json, summary_index.json, summary_index.md, wiki_index.json, nidhogg_manifest.json, nova_usage.jsonl, evolve_cycles.jsonl, evolve.json
• .env contains API keys — never commit it
• test_nova.py is a memory-explorer CLI, not a pytest suite — run it with python mcp/test_nova.py
• See CLAUDE.md for operational instructions and sprint workflow; see docs/ROADMAP.md for shipped-vs-planned split