RecallLattice

Python MCP License: MIT Version

A local-first permanent memory lattice for AI agents. RecallLattice combines SQLite, FTS5, ranked fuzzy recall, typed association graphs, spaced review, and a compact MCP interface without embeddings or a hosted database. Existing v3 installations retain the nigrty runtime/module names for complete compatibility.

Your database stays on your machine. The repository never needs it.

Why RecallLattice

Smarter recall: multi-keyword, stemming, prefix, typo-tolerant, tag-aware ranking.
Connected memory: new facts auto-link to related facts; recall can add one-hop graph context.
Low-token MCP: compact JSON emits each fact once and retrieves full text only on request.
Durable: WAL-mode SQLite, FTS synchronization triggers, integrity checks, and simple backups.
No vector stack: the core uses Python's standard library plus SQLite FTS5.
Full ownership: one portable database file and a localhost-only optional dashboard.
Backwards compatible: upgrades existing nigrty v3 databases in place without changing memory IDs.

Architecture

Hermes / any MCP client
        │ stdio
        ▼
  nigrty_mcp.py ───── compact ranked context
        │
        ▼
    nigrty.py ─────── dedup · scoring · decay · graph
        │
        ▼
  SQLite + FTS5 ───── memories · links · activity · XP
        ▲
        │
  FastAPI dashboard (optional, 127.0.0.1:8799)

Recall ranking

nigrty scores matches using:

Exact phrase relevance.
Exact token and stem matches.
Prefix and typo-tolerant similarity.
Tag matches and query coverage.
Pin status, importance, and memory strength.
Optional one-hop graph neighbors after direct results.

This keeps retrieval deterministic and inspectable while catching queries such as Qran reel vidio for a memory containing Quran Reels ... video.

Install

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

The installer:

preserves an existing ~/.nigrty/nigrty.db;
backs up existing source files;
creates a persistent ~/.nigrty/.venv;
installs MCP and dashboard dependencies;
installs and starts the localhost dashboard service.

Open the dashboard at http://127.0.0.1:8799.

Hermes Agent integration

Add this MCP server to ~/.hermes/config.yaml through Hermes configuration tooling:

mcp_servers:
  nigrty:
    command: /home/YOU/.nigrty/.venv/bin/python
    args:
      - /home/YOU/.nigrty/nigrty_mcp.py
    enabled: true

For an existing nigrty entry, update its interpreter and enable it:

hermes config set mcp_servers.nigrty.command "$HOME/.nigrty/.venv/bin/python"
hermes config set mcp_servers.nigrty.enabled true

Start a new Hermes session after changing MCP configuration.

MCP tools

Tool	Purpose
`nigrty_store`	Store, categorize, tag, deduplicate, and auto-link a fact
`nigrty_recall`	Ranked compact recall with optional graph context
`nigrty_get`	Retrieve one full memory and its links
`nigrty_forget`	Delete one memory
`nigrty_pin` / `nigrty_unpin`	Control critical-memory priority
`nigrty_review`	Strengthen a memory through spaced review
`nigrty_link`	Add a typed graph edge
`nigrty_stats`	Inspect memory and graph health
`nigrty_review_due`	List memories needing review
`nigrty_graph`	Export graph nodes and edges
`nigrty_heatmap`	Summarize activity
`nigrty_export`	Export memory records
`nigrty_prune`	Preview stale low-value records before deletion

Compact versus full recall

Compact recall is the default:

{"query":"project memory","limit":8,"include_related":true,"max_chars":320}

Use "full": true only when the complete matching records are necessary. This progressive-disclosure pattern avoids paying for timestamps and bookkeeping on ordinary recalls.

Python API

import nigrty

saved = nigrty.store(
    "The project uses SQLite FTS5 for local ranked retrieval",
    category="project",
    importance=8,
)

matches = nigrty.recall("SQLite ranked project", limit=5)
print(matches[0]["content"])

Use a custom database path without changing source:

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

Dashboard API

curl http://127.0.0.1:8799/api/stats
curl --get --data-urlencode 'q=ranked memory' http://127.0.0.1:8799/api/search
curl -X POST http://127.0.0.1:8799/api/store \
  -d 'content=One durable fact' -d 'importance=8'

The REST write endpoints use form encoding. The dashboard has no authentication and binds to localhost by default.

Backups and rollback

cp ~/.nigrty/nigrty.db ~/.nigrty/nigrty.db.backup-$(date +%Y%m%d)
./scripts/rollback-local.sh /path/to/pre-upgrade-backup

No migration deletes memories. v3.1 adds FTS maintenance triggers and an internal schema version, then rebuilds the search index from the canonical memories table.

Testing

python -m unittest discover -s tests -v
python -m py_compile nigrty.py nigrty_protocol.py nigrty_mcp.py server.py

The test suite covers deduplication, auto-linking, multi-keyword ranking, typo tolerance, tag filtering, access metadata, FTS store/update/delete synchronization, and compact output.

Privacy

Never commit nigrty.db, exports, backups, or .env files. The included .gitignore blocks these patterns, but inspect staged files before every push.

License

MIT — see LICENSE.

nigrty