The problem: agents remember facts, but forget why

When an AI coding agent works inside a codebase, knowing what a file contains is only half the job. The harder half is remembering why a choice was made six weeks ago, which trade-offs were accepted, and what consequences followed.

Plain vector search is good at finding text matches ("what do we know?"). But it struggles with causal reasoning:

• Why was shadcn/ui chosen over gluestack.io?
• What bug caused us to add a forward-version write guard to the memory engine?
• Which past decision forbids mutation testing in CI?

To solve this, we integrated an external open-source tool called Semantica into our setup. By linking Semantica's causal knowledge graph with ai-badger 0.124.0 prompt hooks and ai-raccoon 1.14.1's persistent memory bank (building on the search quality system introduced in 1.7.0), we turned session reasoning into an automated, auditable decision trail that stays alive across restarts.

What Semantica is (and where to find it)

Semantica (the PyPI package is semantica; the installed console script is named semantica-mcp) is an external open-source MCP server built for session-scoped knowledge graph reasoning.

Instead of just indexing raw text chunks, Semantica tracks entities, relationships, confidence scores, and structured decision records (category, scenario, reasoning, outcome, confidence).

Quick overview

• Tool Type: External Python-based MCP server (semantica v0.6.5+).
• Core Function: Tracks causal decision graphs, extracts entity relationships, and checks precedents during agent runs.
• Where to find: Open source on GitHub and PyPI (pip install semantica).
• Installation:

  pip install semantica

Or register it in your agent's MCP setup (.mcp.json or config.yaml):

  {
    "mcpServers": {
      "semantica": {
        "command": "semantica-mcp"
      }
    }
  }

Three tools for three questions

In our multi-agent workflow, we split knowledge management across three distinct tools:

Solving ephemerality: The ai-raccoon Persistence Bridge ([ADR-0019](https://github.com/Arasz/ai-badger/blob/main/docs/adr/0019-semantica-session-graph-export-and-airaccoon-watch.md))

Semantica's session-scoped design meant valuable decision graphs disappeared when a session ended. Rather than modifying Semantica's internal code, we created the ai-raccoon Persistence Bridge Pattern:

How the bridge works

1. Atomic Exporter: On hook execution or session exit, .ai-badger/skills/semantica-knowledge-graph/scripts/export_semantica_graph.py takes a snapshot of Semantica's nodes, edges, and decisions, writing an atomic JSON file to .ai-raccoon/semantica-graph.json.
2. ai-raccoon Watcher: ai-raccoon maintains an active file watch (memory_watch_add) on .ai-raccoon/semantica-graph.json.
3. Chunking and Ingestion: ai-raccoon automatically parses the graph schema (nodes, edges, decisions), chunking entities and rationale into its encrypted SQLite store (~/.ai-raccoon/memory.db).
4. Cross-Session Recall: In future sessions, memory_search in ai-raccoon returns both textual rationale and exact structural graph relations across restarts.

Automating auditable memory with ai-badger & ai-raccoon

The main advantage here is automation. Nobody needs to hand-format decision logs or manually run export commands.

Combining ai-badger prompt hooks with ai-raccoon background indexing keeps decision tracking hands-off:

1. Automatic Capture: While an agent runs tasks under ai-badger 0.124.0, pre-tool and post-tool hooks record major decisions and verification outcomes.
2. Background Indexing: Notes and exported graph snapshots flow straight into ai-raccoon 1.14.1's project memory bank without manual steps.
3. Auditable Reasoning Chains: When someone asks "why" a decision was made, memory_search retrieves the causal chain (Problem -> Research/Trigger -> Solution -> Verified Outcome).

Real-world example: Auditing skill creation in our session

During a recent session, we asked our agent why three skills (ai-raccoon-state-checklist, ai-text-humanization, and refactoring-fix) were created. Here is the exact reasoning chain retrieved from memory:

Conclusion

Using Semantica for causal reasoning alongside ai-raccoon's persistent storage and ai-badger's automated hooks addresses two frequent hurdles in AI software development: session memory loss and untraceable decision rationale.

Agents no longer make edits in isolation. Every significant architectural choice leaves a persistent, searchable reasoning trail that maintainers and future agent runs can verify.