nigrty

RecallLattice is a permanent local memory layer for AI agents. It turns durable facts into a searchable, typed knowledge lattice and returns only the context that fits the task and token budget.

No vector database. No embedding API. No hosted account. One portable SQLite file.

What makes it different

Related MCP server: Cortex

Start in sixty seconds

git clone https://github.com/Adam-ZS/RecallLattice.git
cd RecallLattice
./scripts/install.sh

Open the private dashboard:

http://127.0.0.1:8799

The installer creates ~/.recall-lattice, builds a persistent virtual environment, preserves an existing database, installs the MCP/dashboard dependencies, and enables the localhost-only dashboard service.

The smart memory pipeline

Save more signal

A batch passes through one consistent path:

1. Normalize each fact.

2. Infer a category when none is supplied.

3. Extract useful technical tags.

4. Merge exact duplicates instead of creating noise.

5. Find related memories and create typed similarity edges.

6. Store the canonical record in SQLite and synchronize FTS5.

Spend fewer tokens

A context request follows a separate retrieval path:

1. Score exact, lexical, stemmed, prefix, fuzzy, and tag matches.

2. Blend relevance with pin status, importance, and memory strength.

3. Optionally add one-hop graph context.

4. Deduplicate records.

5. Fit the strongest content into an exact token budget.

import recall_lattice as brain

pack = brain.context_pack(
    "How does the deployment pipeline work?",
    token_budget=768,
    include_related=True,
)

print(pack["estimated_tokens"], pack["memories"])

Architecture

The standard-library core owns SQLite, FTS5, ranking, graph traversal, decay, and deduplication. MCP and FastAPI are optional interfaces around that same core, so dashboard writes and agent writes behave identically.

MCP configuration

Install with the all extra, or use ./scripts/install.sh:

python -m pip install 'recall-lattice-memory[all]'

Add the server to an MCP-compatible client:

{
  "mcpServers": {
    "recall_lattice": {
      "command": "/home/YOU/.recall-lattice/.venv/bin/python",
      "args": ["/home/YOU/.recall-lattice/recall_lattice_mcp.py"]
    }
  }
}

Hermes Agent YAML:

mcp_servers:
  recall_lattice:
    command: /home/YOU/.recall-lattice/.venv/bin/python
    args:
      - /home/YOU/.recall-lattice/recall_lattice_mcp.py
    enabled: true

Restart the client after changing its MCP configuration.

Nineteen MCP tools

Capture and retrieval

Graph intelligence

Memory lifecycle

Observability and portability

MCP examples

Capture a whole session efficiently

{
  "items": [
    {"content": "Project Aurora uses FastAPI", "category": "project", "importance": 8},
    {"content": "Production deploys require a signed tag", "category": "procedure", "importance": 9},
    "The dashboard binds to localhost"
  ],
  "source": "session-summary"
}

Forge task-specific context

{
  "query": "Aurora production deployment",
  "token_budget": 640,
  "include_related": true
}

Inspect a memory neighborhood

{
  "memory_id": 42,
  "depth": 2,
  "limit": 80
}

The 3D memory observatory

The dashboard is an operational surface, not a decorative landing page.

• Context Forge — search, set a token ceiling, preview the exact packed memories, then copy.

• Interactive brain — drag to rotate; double-click or press EXPAND for fullscreen.

• Neighborhood focus — open a memory and jump directly into its two-hop subgraph.

• Connection suggestions — inspect likely missing edges from the memory modal.

• Batch capture — paste one fact per line and store the entire set in one operation.

• Neural timeline — watch stores, recalls, reviews, links, and merges chronologically.

• Command palette — press Ctrl/⌘ + K to capture, forge, explore, export, review, or open a random memory.

• Keyboard navigation — N new memory, F Context Forge, G fullscreen graph, Esc close.

• Pointer depth — memory cards respond spatially to cursor position.

• Reduced motion — respects the operating-system preference.

The server binds to 127.0.0.1 by default because the dashboard has no authentication.

Python API

import recall_lattice as brain

saved = brain.store(
    "RecallLattice keeps its canonical store in SQLite",
    category="system",
    tags=["SQLite", "local-first"],
    importance=9,
)

matches = brain.recall("local canonical memory", limit=5)
neighbors = brain.neighborhood(saved["id"], depth=2)
suggestions = brain.suggest_links(saved["id"], limit=5)
timeline = brain.timeline(days=30, limit=100)

Use another database without editing source:

export RECALL_LATTICE_DB="$HOME/my-brain/memory.db"

REST API

Interactive endpoint documentation is available at http://127.0.0.1:8799/docs.

Token efficiency

RecallLattice uses three layers to control context cost:

1. Compact MCP serialization omits duplicated bookkeeping.

2. Progressive disclosure keeps full content behind explicit retrieval.

3. Context Forge enforces a caller-selected token ceiling.

A measured three-result compact recall reduced serialized output from 4,566 characters to 1,229 characters: 73.1% less context before applying a Context Forge budget.

Durability and privacy

• SQLite runs in WAL mode.

• FTS5 synchronization is maintained by database triggers.

• Schema upgrades rebuild indexes from the canonical memories table.

• The database is a single portable file.

• Dashboard and API default to localhost.

• No telemetry, hosted database, embedding provider, or API key is required.

• Database files, exports, backups, and environment files are ignored by Git.

Backup manually:

cp ~/.recall-lattice/recall-lattice.db \
   ~/.recall-lattice/recall-lattice.db.backup-$(date +%Y%m%d)

Test and package

python -m unittest discover -s tests -v
python -m py_compile recall_lattice.py recall_lattice_protocol.py recall_lattice_mcp.py server.py
python -m pip wheel . --no-deps -w dist

The suite covers storage, exact deduplication, automatic links, FTS synchronization, hybrid ranking, typo tolerance, tag filters, access metadata, compact serialization, token-budget enforcement, batch capture, graph traversal, timeline previews, and all MCP schemas.

AI-agent setup

llms.txt gives coding agents a compact machine-readable installation guide, architecture summary, tool inventory, and operational constraints.

Contributing

Read CONTRIBUTING.md, open a focused issue, and submit changes through a pull request. main is protected from deletion and force pushes and requires linear history and resolved review conversations.

License

MIT — see LICENSE.