How the Cross-Session Memory System in Agent-Knowledge Works: Architecture Deep Dive

Agent-Knowledge implements a persistent, cross-session memory architecture using a git-synced Markdown knowledge base enriched with hybrid semantic search, a typed knowledge graph, and automated confidence-based pruning to let Claude-based agents retain context across separate runs.

The cross-session memory system in agent-knowledge is defined in the anthropics/claude-plugins-community repository, specifically within the .claude-plugin/marketplace.json file. This system allows Claude agents to survive restarts without losing context by storing observations, decisions, and task history in a local, version-controlled format that supports both fast retrieval and complex relational queries.

Core Architecture Components

The architecture combines file-based persistence with rich indexing capabilities to balance simplicity with powerful retrieval.

Git-Backed Markdown Knowledge Base

At the foundation lies a git-synced Markdown knowledge base where all memories persist as ordinary markdown files. According to the marketplace entry in .claude-plugin/marketplace.json (lines 540-550), this design ensures memories survive process restarts and enable team-wide sharing through standard version control. Each memory entry resides as a discrete file, making the storage transparent, diffable, and human-readable.

Hybrid Search Index (Semantic + TF-IDF)

The system employs a hybrid search approach combining full-text and semantic retrieval. Queries execute against an FTS5 (Full-Text Search 5) index for fast keyword matching, followed by a semantic similarity check using embeddings. This dual-layer approach, described in the memory system documentation, delivers both high precision for exact matches and high recall for conceptually related content.

Typed Knowledge Graph with 11 Edge Types

Beyond flat file storage, agent-knowledge structures memory as a typed knowledge graph. Memory items function as nodes connected by 11 distinct directed edge types, enabling sophisticated graph-traversal queries using BFS (Breadth-First Search). This relational modeling supports complex reasoning chains, allowing agents to answer questions like "what decisions led to this architecture choice?" by traversing the graph structure.

Memory Lifecycle Management

The system actively manages memory quality and relevance through automated scoring and distillation processes.

Confidence and Decay Scoring

Every fact in the knowledge base carries a confidence value that decays over time. As noted in the marketplace configuration, low-confidence or stale facts undergo automatic pruning. This prevents the context window from filling with obsolete information while preserving high-value, frequently reinforced memories.

Automatic Session Distillation

At session termination, the agent runs an automatic session distillation process. This extracts high-value observations from the interaction history and prepares them for persistent storage. The distillation pipeline filters transient noise, retaining only substantive learnings that improve future performance.

Secret Scrubbing Pipeline

Before writing any memory to disk, the system applies automatic secret scrubbing. This safety mechanism detects and removes sensitive information such as API keys, passwords, or tokens from observations, ensuring that persistent storage does not become a security liability.

The Four-File Memory Stack

The architecture implements a layered four-file memory stack referenced in .claude-plugin/marketplace.json (lines 871-880). This stack separates concerns across distinct tiers:

• project-memory: Core facts and domain knowledge about the codebase
• decisions-log: Architectural decisions and their rationales
• task-history: Completed and pending task contexts
• Raw observations: Unprocessed session outputs

This layering allows agents to load only the most relevant tier during startup, optimizing context window usage and retrieval speed.

File-Based Persistence Mechanisms

Agent-knowledge extends basic file storage with specialized I/O primitives for complex data types.

Tesseract Skill (Anchors, Shelves, Bulk-Beings)

The /tesseract skill, detailed in .claude-plugin/marketplace.json (lines 3988-3994), implements cross-session persistence through three file-based abstractions:

• Anchors: Lightweight pointers referencing specific memory locations
• Shelves: Collections of related memory items
• Bulk-beings: Large binary or text blobs stored as regular files

These primitives enable the system to handle everything from simple string lookups to large artifact storage without requiring external databases.

Per-File Annotations

Individual source files can embed per-file annotations that serve as memory pointers. As noted in the marketplace entry (lines 662-664), these annotations allow the agent to retrieve context tied to specific files when they are edited in future sessions, creating a cohesive editing experience across discontinuous work periods.

Interacting with the Memory System

Users interact with the cross-session memory system through MCP tools that read and write the git-backed store. Typical workflows include:

# Distill current session observations into persistent knowledge

/learn <topic>

# Query the hybrid search index for specific facts

/recall "how does the auth flow work?"

# Inspect decision history for a specific project

/memory decisions-log --project my-app

# Manually trigger garbage collection of stale entries

/memory clean --max-age 30d

When a new session starts, the agent automatically loads relevant memory files filtered by confidence thresholds, decay scores, and relevance rankings, injecting them into the prompt context for a "warm start" rather than a blank slate.

Summary

• Agent-knowledge stores all memories as git-synced Markdown files in .claude-plugin/marketplace.json, enabling version-controlled persistence across sessions.
• Hybrid search combines FTS5 full-text indexing with embedding-based semantic similarity for optimal retrieval.
• Typed knowledge graph with 11 directed edge types supports BFS traversal for relational reasoning about decisions and dependencies.
• Confidence decay automatically prunes stale or low-confidence facts to maintain context window efficiency.
• Four-file memory stack (project-memory, decisions-log, task-history, observations) enables tiered loading strategies.
• Tesseract skill provides file-based abstractions (anchors, shelves, bulk-beings) for complex persistence patterns.
• Automatic distillation and secret scrubbing ensure only safe, high-value information persists between sessions.

Frequently Asked Questions

How does agent-knowledge prevent sensitive data from persisting across sessions?

The system implements an automatic secret scrubbing pipeline that executes before any session distillation writes to disk. This process detects patterns matching API keys, passwords, tokens, and other credentials, removing them from observations before they reach the git-backed Markdown store defined in .claude-plugin/marketplace.json.

What makes the search in agent-knowledge "hybrid"?

Agent-knowledge combines FTS5 (Full-Text Search 5) for fast keyword-based retrieval with semantic similarity search using vector embeddings. Queries first execute against the FTS5 index for immediate candidate selection, then undergo semantic ranking to surface conceptually related content that might not share exact keyword matches.

Can multiple agents share the same cross-session memory?

Yes. Because the architecture uses a git-synced Markdown knowledge base, the memory files function as standard repository content. Teams can commit .claude-plugin/marketplace.json configurations and associated memory files to version control, allowing multiple Claude instances to synchronize state through standard Git workflows.

What happens to old memories that are no longer relevant?

The system applies confidence and decay scoring to every fact. Each memory item carries a confidence value that degrades over time; when scores fall below configurable thresholds, the automatic pruning process removes them during routine maintenance cycles or when the /memory clean command executes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}