RecallLattice

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.

Related MCP server: Synapto

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:

1. Exact phrase relevance.

2. Exact token and stem matches.

3. Prefix and typo-tolerant similarity.

4. Tag matches and query coverage.

5. Pin status, importance, and memory strength.

6. 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

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.