Metadata-Version: 2.4
Name: engram-agent-memory
Version: 0.4.1
Summary: Persistent, queryable knowledge storage for AI agents. Markdown source + SQLite + manifest fallback.
Author-email: Stryder Tech <admin@strydertech.com>
License: MIT
Project-URL: Homepage, https://github.com/Driftah9/engram-agent-memory
Project-URL: Documentation, https://github.com/Driftah9/engram-agent-memory#readme
Project-URL: Repository, https://github.com/Driftah9/engram-agent-memory.git
Project-URL: Issues, https://github.com/Driftah9/engram-agent-memory/issues
Keywords: ai,memory,knowledge,agent,sqlite,persistent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```bash
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

```markdown
---
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

```python
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](docs/api.md) — Every method and parameter
- [Architecture](docs/architecture.md) — How it works under the hood
- [Technical Details](docs/technical.md) — File formats, schema, internals
- [Contributing](CONTRIBUTING.md) — How to submit improvements

---

## Contributing

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

---

## License

MIT — free to use, modify, and distribute. See [LICENSE](LICENSE).

---

Built by [Stryder Tech](https://strydertech.com) · Questions: admin@strydertech.com
