engram-agent-memory

Give your AI agent a memory that survives anything.

engram-agent-memory lets AI agents store knowledge, look it up instantly, and keep working even if the database goes down — because your knowledge is always backed by plain text files.

---

The problem it solves

AI agents are forgetful by default. Every session starts fresh. Workarounds like dumping everything into a context window are slow, expensive, and hit limits fast.

engram-agent-memory gives your agent a proper knowledge base:

• Store what it learns, organized by type
• Search it in milliseconds
• Recover automatically if anything breaks

---

How it works

You keep your knowledge in simple markdown files — one topic per file, organized with a few lines of header info. engram-agent-memory builds a fast search index on top of those files, so your agent can find exactly what it needs without reading everything.

If the index ever fails or gets corrupted, the agent falls back to a backup index file that never goes down. No data loss, no downtime.

Your markdown files
       ↓
   Fast search index (SQLite)
       ↓
   Your agent gets answers in milliseconds

   (If index breaks → backup index takes over automatically)

---

Quick start

Install

pip install engram-agent-memory

The distribution name is engram-agent-memory (the engram-memory name on PyPI belongs to an unrelated project). The import name is just engram.

Or install from source:

pip install git+https://github.com/Driftah9/engram-agent-memory.git
# or, editable:
git clone https://github.com/Driftah9/engram-agent-memory.git
cd engram-agent-memory && pip install -e .

Pure standard library — no runtime dependencies to install. Import with from engram import ....

Semantic search is the one optional extra: it calls a local Ollama endpoint for embeddings if you have one running, and falls back to keyword-only search if you don't. Nothing to configure either way, and still no cloud API or vector database.

Create a knowledge file

---
name: user-profile
type: user
description: Who the user is and their preferences
---

Name: Alice
Location: San Francisco
Prefers: concise answers, no jargon

## Preferences
Short responses unless asked for detail.

## Constraints
Budget is limited. Always flag costs upfront.

Use it in your agent

from engram import MemoryStore

# Point it at your folder of markdown files
store = MemoryStore("./knowledge")
store.build()  # Builds the search index

# Search for what you need
results = store.query("budget")
# → Tells you which file and which lines have the answer

# Read just those lines — not the whole file
content = store.read_lines(results[0]["file_path"],
                           results[0]["line_start"],
                           results[0]["line_end"])
# → "Budget is limited. Always flag costs upfront."

# Or ask in plain language — smart_recall handles full sentences
hits = store.smart_recall("what's the user's spending situation?")
# → [{'text': '[user-profile > Constraints] Budget is limited...',
#     'source': 'engram:user_profile.md:12-14', 'score': 0.9}]

---

What kind of knowledge can it store?

engram-agent-memory uses four categories to keep things organized:

Type	What goes here	Examples
user	Who the user is	Name, location, preferences, constraints
feedback	Rules you've learned	"User hates bullet lists", "always confirm before deleting"
project	Ongoing work	Current goals, decisions made, blockers
reference	Outside information	Research findings, documentation notes

Your agent can search all of them at once, or narrow to just the type it needs.

---

Key features

Fast search Find relevant knowledge in under a millisecond. Works even across hundreds of files.

Precise retrieval Results include the exact file and line numbers where the answer lives — not the whole document. Your agent loads only what it needs.

Natural-language recall smart_recall() takes a full sentence, strips the noise words, and returns the best-matching section with its line pointers — so plain-language questions work, not just keyword lookups. Since 0.4.0 it scores keyword overlap and vector similarity against a relevance floor, so results are variable-k: k caps the list rather than filling it, and getting back nothing means nothing was actually relevant. That's deliberate — padding results to k with weak matches looked like better recall while burning context on noise.

Hybrid semantic search hybrid_query() combines keyword (FTS5) matching with vector similarity, so paraphrases and synonyms are found even when they share no words with the stored text. Embeddings are generated by a local Ollama endpoint (default nomic-embed-text) and stored right in the SQLite file — no external vector database, no cloud API. If Ollama isn't running, it degrades gracefully to keyword-only search.

Incremental indexing build() re-parses only the files that changed since the last run (tracked by modification time), so rebuilds stay fast as your knowledge base grows. build(full=True) forces a complete rebuild when you need one.

Crash-proof fallback If the search index fails, a backup JSON index takes over with no code changes required. Your knowledge is never lost.

Relations between topics (MOC graph) Link knowledge files together — either with see_also in the header or by writing [[node-name]] inline in the body. Your agent can follow those connections automatically, turning your notes into a navigable map of content.

No external services Runs entirely on your machine. No APIs, no cloud services, no vendor lock-in. Just Python and a SQLite file.

---

When to use engram-agent-memory

Good fit:

• Single AI agent that needs to remember things across sessions
• Small team sharing a knowledge base
• Projects where you want knowledge version-controlled in git
• Anywhere you need fast, reliable retrieval without setting up a server

Not the right fit:

• Large-scale distributed systems with many simultaneous writers
• Pure vector search at massive scale (hybrid semantic search is built in via a local Ollama endpoint, but for millions of vectors with heavy ANN tuning, use a dedicated vector database)
• Terabytes of data (this is designed for files-on-disk scale)

---

Full documentation

• API Reference — Every method and parameter
• Architecture — How it works under the hood
• Technical Details — File formats, schema, internals
• Contributing — How to submit improvements

---

Contributing

Found a bug? Have an idea? Read CONTRIBUTING.md first — it explains what makes a good contribution. Then open an issue.

---

License

MIT — free to use, modify, and distribute. See LICENSE.

---

Built by Stryder Tech · Questions: admin@strydertech.com