Content
# Engram
> Give your AI agents a memory that persists, searches by meaning, and lives in plain files on your own machine.
## Why Engram?
AI agents forget everything between sessions. Every conversation starts from scratch — no recall of past decisions, no accumulated knowledge, no continuity. You can wire up a database, but then you're running infrastructure and writing queries instead of building your agent.
Engram gives agents persistent memory through a simple REST API. Write a memory, search for it later by meaning, and everything is stored as readable Markdown files you control. No cloud service, no API keys, no database to manage. Point it at a directory and start storing memories.
When you write a memory, Engram checks whether you already have a similar one. If it's genuinely new, it's added. If it's a duplicate, the existing one is kept. If it's an update, the old memory is replaced — preserving its importance score. You decide how strict the deduplication is, and you can bring your own LLM to make the call when similarity is ambiguous.
Each agent gets its own namespace, so multiple agents can share the same Engram instance without stepping on each other. Search combines vector similarity with keyword matching, weighted by importance. If embeddings aren't available, CRUD still works — search returns 503 until you fix the embedding provider.
## Features
- **Persistent memory** — store text memories that survive across sessions, each one a human-readable Markdown file
- **Smart deduplication** — every write checks for similar memories: add new ones, ignore duplicates, or update existing ones with preserved importance
- **LLM-assisted decisions** — when similarity is ambiguous, consult a local LLM to decide whether to add, update, or ignore
- **Semantic search** — find memories by meaning, not just exact keyword matches
- **Importance scoring** — tag memories with priority; scores decay over time and get bumped on retrieval
- **Multi-agent isolation** — each agent gets its own namespace; no overlap, no conflicts
- **Local-first and private** — no cloud, no API keys, no telemetry. Your data stays on your machine
- **Human-readable storage** — every memory is a Markdown file you can read, edit, and version-control
- **Automatic indexing** — memories are chunked and indexed as you write them, no manual rebuilds
- **Graceful degradation** — CRUD works even without embeddings; search returns 503 until the provider is available
## Who It's For
Engram is for developers building AI agents who need those agents to remember things across conversations. If you're working with LLM-based tools, chatbots, or autonomous agents and need persistent, searchable memory without running a database server, Engram solves that problem.
## How It Works
Engram runs a local HTTP server. Agents interact with it through a REST API — create, read, list, delete, and search memories. Each memory is stored as a Markdown file with YAML frontmatter inside a vault directory you choose. A LanceDB index handles search, combining vector embeddings with keyword matching and importance-weighted reranking.
When you create a memory, the smart write pipeline runs: the content is embedded, compared against existing memories, and a decision is made — add it as new, update an existing one, or ignore it as a duplicate. When you search, results are ranked by relevance and importance, and each result's importance score is decayed and bumped so frequently accessed memories stay fresh.
When you create a memory, it looks like this on disk:
```markdown
---
agent: my-agent
created: "2026-05-03T12:00:00+00:00"
id: deployed-v2-to-production-my-agent-2026-05-03
importance: 0.9
importance_updated: "2026-05-03T12:00:00+00:00"
tags:
- deploy
- production
type: memory
updated: "2026-05-03T12:00:00+00:00"
---
Deployed v2 to production
```
You can open this file in any text editor, edit it directly, or put the vault directory under version control. The search index rebuilds from these files automatically.
## Quick Start
### 1. Install dependencies
```bash
uv sync --extra dev
```
This command works on all platforms. It creates a virtual environment and installs Engram with all dependencies. Do not create a virtual environment manually — `uv` manages its own `.venv`.
### 2. Create a vault directory
Engram stores memories as Markdown files inside a vault directory. Choose any location — for example:
| Platform | Example path |
| -------- | ---------------------------- |
| macOS | `/Users/you/.engram/vault` |
| Linux | `/home/you/.engram/vault` |
| Windows | `C:\Users\you\.engram\vault` |
You can also point Engram at an existing Obsidian vault — any directory works.
Create the directory you chose:
```bash
# macOS / Linux
mkdir -p ~/.engram/vault
```
```powershell
# Windows PowerShell
New-Item -ItemType Directory -Path "$env:USERPROFILE\.engram\vault" -Force
```
```cmd
# Windows CMD
mkdir "%USERPROFILE%\.engram\vault"
```
### 3. Configure environment variables
Copy the example configuration file:
```bash
# macOS / Linux
cp .env.example .env
```
```powershell
# Windows PowerShell
Copy-Item .env.example .env
```
```cmd
# Windows CMD
copy .env.example .env
```
Then edit `.env` and set `ENGRAM_VAULT_PATH` to the directory you created:
```ini
# macOS / Linux
ENGRAM_VAULT_PATH=~/.engram/vault
```
```ini
# Windows
ENGRAM_VAULT_PATH=C:\Users\you\.engram\vault
```
`ENGRAM_VAULT_PATH` is the only required variable. All others have defaults.
### 4. Start the server
```bash
uv run engram start
```
This command works on all platforms. When the server starts, you will see:
```
2026-05-03 12:00:00.000 | INFO | engram.cli.cli:start:142 - Starting Engram on 127.0.0.1:7777
INFO: Started server process [12345]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:7777 (Press CTRL+C to quit)
```
The timestamp, line number, and PID vary each time. The key line is `Uvicorn running on http://127.0.0.1:7777`.
### 5. Verify the server is running
```bash
curl http://127.0.0.1:7777/health
```
This command is the same on all platforms.
Response:
```json
{
"status": "healthy",
"version": "1.2.0",
"components": {
"vault": "healthy",
"lancedb": "healthy",
"embeddings": "healthy"
}
}
```
On Windows PowerShell, use `Invoke-RestMethod http://127.0.0.1:7777/health | ConvertTo-Json` instead.
### 6. Stop the server
Press Ctrl+C in the terminal running the server. If running as a daemon:
```bash
uv run engram stop
```
This command works on all platforms.
## CLI Reference
### `engram start`
Start the Engram server.
```bash
# Start in foreground (default)
uv run engram start
# Start on a custom host and port
uv run engram start --host 0.0.0.0 --port 9000
# Start as a background daemon
uv run engram start --daemon
```
| Flag | Default | Description |
| ---------------- | -------------------------------- | -------------------------- |
| `--host TEXT` | `127.0.0.1` (from `ENGRAM_HOST`) | Host address to bind to |
| `--port INTEGER` | `7777` (from `ENGRAM_PORT`) | Port to bind to |
| `--daemon`, `-d` | off | Run as a background daemon |
In foreground mode, press Ctrl+C to stop. In daemon mode, use `engram stop`.
On Windows, daemon mode uses `CREATE_NEW_PROCESS_GROUP` (`start_new_session=True`). If it does not work as expected, use foreground mode (the default).
### `engram stop`
Stop a running Engram daemon.
```bash
uv run engram stop
```
If no server is running:
```
No running Engram server found
```
Exit code: 1. On Windows, the stop command uses `taskkill` instead of `SIGTERM`.
## REST API Reference
All memory endpoints are prefixed with `/agents/{agent_id}`. The `agent_id` is a string that identifies the agent namespace (for example, `my-agent`). The following characters are rejected with a 400 error: path separators (`/`, `\`, `..`) and Windows-illegal filename characters (`< > : " | ? *`).
### Health Check
```bash
curl http://127.0.0.1:7777/health
```
This command is the same on all platforms.
Response (`200`):
```json
{
"status": "healthy",
"version": "1.2.0",
"components": {
"vault": "healthy",
"lancedb": "healthy",
"embeddings": "healthy"
}
}
```
Response when the vault directory is missing (`503`):
```json
{
"status": "unhealthy",
"version": "1.2.0",
"components": {
"vault": "unhealthy",
"lancedb": "unhealthy",
"embeddings": "unhealthy"
}
}
```
### Write a Memory
When you write a memory, Engram checks for similar existing memories first. There are three possible outcomes:
- **added** — no similar memory found, or the similarity is below the add threshold. A new memory is created. Returns `201`.
- **updated** — a similar memory exists and the LLM (or threshold) decides the incoming content replaces it. The old memory is deleted and a new one is created with preserved importance. Returns `200`.
- **ignored** — a very similar memory already exists (above the ignore threshold). No new memory is written. Returns `200` with the existing memory's ID.
**macOS / Linux:**
```bash
curl -X POST http://127.0.0.1:7777/agents/my-agent/memories \
-H "Content-Type: application/json" \
-d '{"content":"The quick brown fox jumps over the lazy dog","tags":["test","example"],"importance":0.8}'
```
**Windows CMD:**
```cmd
curl -X POST http://127.0.0.1:7777/agents/my-agent/memories -H "Content-Type: application/json" -d "{\"content\":\"The quick brown fox jumps over the lazy dog\",\"tags\":[\"test\",\"example\"],\"importance\":0.8}"
```
Request body fields:
| Field | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------------- |
| `content` | string | yes | Memory text (minimum 1 character) |
| `tags` | string[] | no | List of tags (default: `[]`) |
| `importance` | float | no | Importance score 0.0 to 1.0 (default: `0.5`) |
Response for **added** (`201`):
```json
{
"decision": "added",
"id": "the-quick-brown-fox-jumps-over-the-lazy-dog-my-agent-2026-05-03",
"similarity_score": null
}
```
Response for **updated** (`200`):
```json
{
"decision": "updated",
"id": "the-quick-brown-fox-jumps-over-the-lazy-dog-my-agent-2026-05-03",
"similarity_score": 0.72
}
```
Response for **ignored** (`200`):
```json
{
"decision": "ignored",
"id": "existing-memory-id-my-agent-2026-05-03",
"similarity_score": 0.95
}
```
The `id` is generated from the content, agent ID, and current date. The `similarity_score` shows how similar the incoming content was to the best match (`null` for added memories with no match). The `id` and `similarity_score` values will differ each time — use the values returned by your own response.
### List Memories
```bash
curl http://127.0.0.1:7777/agents/my-agent/memories
```
This command is the same on all platforms.
Response (`200`): an array of memory objects. Returns `[]` if the agent has no memories.
```json
[
{
"id": "the-quick-brown-fox-jumps-over-the-lazy-dog-my-agent-2026-05-03",
"agent": "my-agent",
"type": "memory",
"importance": 0.8,
"tags": ["test", "example"],
"created": "2026-05-03T12:00:00+00:00",
"updated": "2026-05-03T12:00:00+00:00",
"importance_updated": "2026-05-03T12:00:00+00:00",
"body": "The quick brown fox jumps over the lazy dog"
}
]
```
### Read a Memory
```bash
curl http://127.0.0.1:7777/agents/my-agent/memories/the-quick-brown-fox-jumps-over-the-lazy-dog-my-agent-2026-05-03
```
This command is the same on all platforms. Response (`200`): a single memory object in the same format as List Memories.
Response (`404`):
```json
{ "detail": "Memory not found" }
```
### Delete a Memory
```bash
curl -X DELETE http://127.0.0.1:7777/agents/my-agent/memories/the-quick-brown-fox-jumps-over-the-lazy-dog-my-agent-2026-05-03
```
This command is the same on all platforms. Response (`204`): empty body on success.
Response (`404`):
```json
{ "detail": "Memory not found" }
```
### Search Memories
**macOS / Linux:**
```bash
curl "http://127.0.0.1:7777/agents/my-agent/memories/search?q=python&limit=5"
```
**Windows CMD:**
```cmd
curl "http://127.0.0.1:7777/agents/my-agent/memories/search?q=python&limit=5"
```
Query parameters:
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------------------------- |
| `q` | string | yes | Search query (minimum 1 character) |
| `limit` | integer | no | Maximum results to return, 1–100 (default: 10) |
Response (`200`): an array of search result objects ranked by relevance. Importance scores are updated on each retrieval — decayed by time since last access, then bumped by the hit increment.
```json
[
{
"id": "python-programming-basics-my-agent-2026-05-03",
"score": 0.87,
"importance": 0.5,
"chunk": "Python is a versatile programming language...",
"agent": "my-agent",
"created": "2026-05-03T12:00:00+00:00"
}
]
```
**Missing query parameter** (`422`):
```json
{
"detail": [
{
"type": "missing",
"loc": ["query", "q"],
"msg": "Field required"
}
]
}
```
**Search unavailable** (`503`):
```json
{ "detail": "Search index not available" }
```
```json
{ "detail": "Search unavailable: embedding provider is not configured" }
```
### Error Responses
| Status | When |
| ------ | ---------------------------------------------------------------------------- |
| `400` | Agent ID or memory ID contains path separators or Windows-illegal characters |
| `404` | Memory not found (on read or delete) |
| `422` | Request body validation failed (for example, empty `content`) |
**Agent ID with illegal characters** (`400`):
```json
{ "detail": "agent_id contains illegal characters: 'bad<agent'" }
```
**Memory ID with path traversal** (`400`):
```json
{ "detail": "Invalid memory_id: 'test-bad..agent-2026-05-03'" }
```
**Memory not found** (`404`):
```json
{ "detail": "Memory not found" }
```
**Empty content** (`422`):
```json
{
"detail": [
{
"type": "string_too_short",
"loc": ["body", "content"],
"msg": "String should have at least 1 character",
"input": "",
"ctx": { "min_length": 1 }
}
]
}
```
## Smart Write Pipeline
When you write a memory, the smart write pipeline runs automatically. You don't configure it separately — it's built into the write endpoint. Here's how it decides what to do:
1. **Embed** the incoming content
2. **Find similar** — search the index for the top 3 most similar memories for the same agent
3. **Threshold check**:
- Similarity below `SIMILARITY_ADD_THRESHOLD` (default 0.3) → **add** as new
- Similarity at or above `SIMILARITY_IGNORE_THRESHOLD` (default 0.92) → **ignore** as duplicate
- Similarity between the two thresholds → **consult LLM**
4. **LLM consultation** — send the incoming content and similar memories to a local Ollama model, which decides add, update, or ignore
5. **Execute** — add a new memory, update the existing one (preserving its importance), or do nothing
If the LLM is unreachable, the pipeline falls back to "add" — keeping your data is always preferred over losing it.
## Importance Scoring
Every memory has an importance score between 0.0 and 1.0. You set it when you create a memory (default: 0.5). The score changes in two ways:
- **Decay** — importance decreases over time based on a half-life (default: 7 days). A memory that hasn't been accessed in 7 days has its importance halved.
- **Retrieval bump** — every time a memory appears in search results, its importance is bumped by the hit increment (default: 0.05), then clamped to 1.0.
Decay is lazy — it's only calculated when a memory is retrieved, not on a schedule. This means importance stays accurate without any background jobs.
When the smart write pipeline updates a memory, the old memory's importance is preserved on the new one.
## Embedding Providers
Search requires an embedding provider to vectorize memories. Engram supports two providers:
1. **Ollama** (default) — runs locally at `http://localhost:11434` using the `nomic-embed-text` model. Start Ollama before Engram: `ollama serve`, then pull the model: `ollama pull nomic-embed-text`.
2. **fastembed** — runs in-process with no external service. Uses the `BAAI/bge-small-en-v1.5` model. Fallback only; set `ENGRAM_EMBEDDING_PROVIDER=fastembed` to use it directly.
When Ollama is unavailable and `ENGRAM_EMBEDDING_AUTOFALLBACK=true` (the default), Engram automatically falls back to fastembed. If both providers fail, the server starts without search — CRUD still works, search returns `503`.
On Windows, the onnxruntime dependency that fastembed requires may fail to load. If you see a 503 error from search, start Ollama and let Engram use it as the embedding provider instead.
## Configuration
All configuration uses environment variables with the `ENGRAM_` prefix. Set them directly or via a `.env` file in the working directory.
**Required:**
| Variable | Default | Description |
| ------------------- | ------- | --------------------------------------------------------- |
| `ENGRAM_VAULT_PATH` | — | Path to the vault directory where memory files are stored |
**Optional:**
| Variable | Default | Description |
| ------------------------------------ | --------------------------- | ---------------------------------------------------------- |
| `ENGRAM_HOST` | `127.0.0.1` | Server bind address |
| `ENGRAM_PORT` | `7777` | Server bind port |
| `ENGRAM_IMPORTANCE_INITIAL_SCORE` | `0.5` | Default importance score for new memories |
| `ENGRAM_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `ENGRAM_LOG_FILE` | `~/.engram/logs/engram.log` | Path to the log file |
| `ENGRAM_LOG_ROTATION` | `10 MB` | Log rotation size threshold |
| `ENGRAM_LOG_RETENTION` | `7 days` | Log retention period |
| `ENGRAM_STATE_FILE` | `~/.engram/state.json` | Path to the PID state file (used by start and stop) |
| `ENGRAM_EMBEDDING_PROVIDER` | `ollama` | Embedding provider: `ollama` or `fastembed` |
| `ENGRAM_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name (provider-specific) |
| `ENGRAM_EMBEDDING_AUTOFALLBACK` | `true` | Auto-fallback to fastembed if Ollama is unavailable |
| `ENGRAM_CHUNK_MAX_TOKENS` | `512` | Maximum tokens per chunk for semantic chunking |
| `ENGRAM_CHUNK_OVERLAP_TOKENS` | `50` | Overlap tokens between adjacent chunks |
| `ENGRAM_RRF_K` | `10` | RRF constant for hybrid search fusion |
| `ENGRAM_IMPORTANCE_RERANK_WEIGHT` | `0.3` | Weight for importance score in reranking (0.0 to 1.0) |
| `ENGRAM_INDEX_PATH` | `~/.engram/index` | Path to the LanceDB index directory |
| `ENGRAM_SIMILARITY_ADD_THRESHOLD` | `0.3` | Below this similarity, always add as new memory |
| `ENGRAM_SIMILARITY_IGNORE_THRESHOLD` | `0.92` | At or above this similarity, ignore as duplicate |
| `ENGRAM_IMPORTANCE_DECAY_HALFLIFE` | `7.0` | Half-life in days for importance decay |
| `ENGRAM_IMPORTANCE_HIT_INCREMENT` | `0.05` | Importance bump on each search retrieval |
| `ENGRAM_LLM_MODEL` | `llama3` | Ollama model name for smart write LLM consultation |
| `ENGRAM_LLM_HOST` | `http://localhost:11434` | Ollama host URL for smart write LLM consultation |
**Reserved (accepted but unused):**
| Variable | Default | Note |
| ---------------------- | ------- | ---------------------------- |
| `ENGRAM_OBSIDIAN_MODE` | `true` | No effect in current version |
| `ENGRAM_SHARED_MODE` | `false` | No effect in current version |
The `.env.example` file in the repository root contains all variables with their defaults.
## End-to-End Walkthrough
This walkthrough creates a memory, reads it, searches for it, and deletes it. Use the `my-agent` agent ID throughout.
**Step 1: Start the server**
```bash
uv run engram start
```
**Step 2: Create a memory**
POST requests with JSON bodies require different quoting on Windows CMD. See Write a Memory for the Windows CMD variant.
**macOS / Linux:**
```bash
curl -X POST http://127.0.0.1:7777/agents/my-agent/memories \
-H "Content-Type: application/json" \
-d '{"content":"Deployed v2 to production on Saturday","tags":["deploy","production"],"importance":0.9}'
```
**Windows CMD:**
```cmd
curl -X POST http://127.0.0.1:7777/agents/my-agent/memories -H "Content-Type: application/json" -d "{\"content\":\"Deployed v2 to production on Saturday\",\"tags\":[\"deploy\",\"production\"],\"importance\":0.9}"
```
The response includes a `decision` and `id` field — note the `id` for the next steps. The `id`, `decision`, and `similarity_score` will differ based on whether similar memories exist:
```json
{
"decision": "added",
"id": "deployed-v2-to-production-on-saturday-my-agent-2026-05-03",
"similarity_score": null
}
```
**Step 3: Read the memory**
Use the `id` from step 2. Your `id` will contain today's date instead of `2026-05-03`:
```bash
curl http://127.0.0.1:7777/agents/my-agent/memories/deployed-v2-to-production-on-saturday-my-agent-2026-05-03
```
This command is the same on all platforms.
**Step 4: Search for the memory**
**macOS / Linux:**
```bash
curl "http://127.0.0.1:7777/agents/my-agent/memories/search?q=production+deploy&limit=5"
```
**Windows CMD:**
```cmd
curl "http://127.0.0.1:7777/agents/my-agent/memories/search?q=production+deploy&limit=5"
```
The search returns ranked results with relevance scores:
```json
[
{
"id": "deployed-v2-to-production-on-saturday-my-agent-2026-05-03",
"score": 0.87,
"importance": 0.9,
"chunk": "Deployed v2 to production on Saturday",
"agent": "my-agent",
"created": "2026-05-03T12:00:00+00:00"
}
]
```
**Step 5: List all memories**
```bash
curl http://127.0.0.1:7777/agents/my-agent/memories
```
Returns an array containing the memory from step 2. This command is the same on all platforms.
**Step 6: Delete the memory**
Use the `id` from step 2:
```bash
curl -X DELETE http://127.0.0.1:7777/agents/my-agent/memories/deployed-v2-to-production-on-saturday-my-agent-2026-05-03
```
Returns `204` with an empty body. This command is the same on all platforms.
**Step 7: Verify deletion**
```bash
curl http://127.0.0.1:7777/agents/my-agent/memories
```
Returns `[]`. This command is the same on all platforms.
**Step 8: Stop the server**
Press Ctrl+C in the terminal running the server, or:
```bash
uv run engram stop
```
This command works on all platforms.
## Troubleshooting
### ValidationError: vault_path field required
```
pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings
vault_path
Field required
```
The `ENGRAM_VAULT_PATH` environment variable is not set. Set it before starting the server.
**macOS / Linux:**
```bash
export ENGRAM_VAULT_PATH="$HOME/.engram/vault"
```
```powershell
# Windows PowerShell
$env:ENGRAM_VAULT_PATH = "$env:USERPROFILE\.engram\vault"
```
```cmd
# Windows CMD
set ENGRAM_VAULT_PATH=%USERPROFILE%\.engram\vault
```
Or edit the `.env` file and set `ENGRAM_VAULT_PATH` to the path you chose for your vault directory.
### No running Engram server found
```
No running Engram server found
```
The `engram stop` command cannot find a running server. Either the server was never started, or it crashed without cleaning up its state file. If a stale state file exists, `engram start` removes it automatically before starting.
### Port 7777 already in use
```
ERROR: [Errno 98] Address already in use (or [WinError 10048] on Windows)
```
Another process is using port 7777. Use a different port:
```bash
uv run engram start --port 8080
```
Or find and stop the process using port 7777:
**macOS / Linux:**
```bash
lsof -i :7777
kill <PID>
```
**Windows PowerShell:**
```powershell
Get-NetTCPConnection -LocalPort 7777 | Select-Object OwningProcess
Stop-Process -Id <PID>
```
**Windows CMD:**
```cmd
netstat -ano | findstr :7777
taskkill /PID <PID> /F
```
### `'cp' is not recognized as an internal or external command
```
'cp' is not recognized as an internal or external command
```
The `cp` command is Unix-only. On Windows CMD, use `copy .env.example .env`. On Windows PowerShell, use `Copy-Item .env.example .env`.
### Empty content rejected with 422
```json
{
"detail": [
{
"type": "string_too_short",
"loc": ["body", "content"],
"msg": "String should have at least 1 character"
}
]
}
```
The `content` field is required and must be at least 1 character. Provide non-empty content in the request body.
### Daemon fails to start on first attempt
```
Daemon failed to start on 127.0.0.1:7777. Process may have exited (PID 12345).
```
On the first run, the server may need more than a few seconds to initialize (embedding model downloads, index creation). The daemon timeout is 30 seconds. If it still fails, try running in foreground mode first to see startup logs:
```bash
uv run engram start
```
If foreground mode works, the daemon should work on subsequent attempts since model files are cached.
### Search returns 503
```json
{ "detail": "Search unavailable: embedding provider is not configured" }
```
Neither Ollama nor fastembed could be loaded. On Windows, this is typically caused by the onnxruntime DLL failing to load. The server starts without search, but CRUD operations still work. To resolve:
- Start Ollama: `ollama serve` (then pull the model: `ollama pull nomic-embed-text`)
- Or set `ENGRAM_EMBEDDING_PROVIDER=fastembed` in your `.env` file (may require Visual C++ Redistributable on Windows)
```json
{ "detail": "Search index not available" }
```
The search index has not been initialized. This means the server started without embedding support. See the resolution steps above.
### Smart write always adds (never deduplicates)
If Ollama is not running, the LLM consultation falls back to "add" every time. Deduplication still works at the threshold level — memories with similarity at or above `ENGRAM_SIMILARITY_IGNORE_THRESHOLD` (default 0.92) are still ignored. Only the ambiguous zone between 0.3 and 0.92 defaults to "add" instead of consulting the LLM.
To enable LLM-assisted decisions in the ambiguous zone:
1. Install Ollama: see [ollama.com](https://ollama.com)
2. Pull a model: `ollama pull llama3`
3. Start Ollama: `ollama serve`
4. If Ollama runs on a non-default host, set `ENGRAM_LLM_HOST` in your `.env` file
## Known Runtime Warnings
When running `uv sync --extra dev`, you may see:
```
Resolved 72 packages in 2ms
Checked 69 packages in 13ms
```
The exact package count and time vary. This is normal — `uv` is resolving and checking dependencies. No action required.
When running `engram start` for the first time, Engram creates the `engram` subdirectory inside your vault path. This is expected — the health check verifies this directory exists.
If you created a virtual environment manually before running `uv sync`, you may see:
```
warning: `VIRTUAL_ENV=venv` does not match the project environment path `.venv` and will be ignored
```
This is harmless. `uv run` uses its own `.venv` and ignores the manual environment. You can delete your manually created virtual environment directory.
## Evaluation Results
v1.1 retrieval evaluation (24 queries, golden set):
| Metric | v1.1 | v1.2 | Change |
| ---------- | ------- | -------- | ------ |
| P@1 | 0.3478 | 0.6957 | +100% |
| R@5 | 1.0 | 1.0 | = |
| MRR@10 | 0.5841 | 0.8152 | +39% |
| Latency@10 | 5324 ms | 18561 ms | +249% |
Precision and MRR improved significantly with the smart write pipeline and importance-weighted reranking. Latency increased because v1.2 updates importance scores on every search result (decay + bump).
## What's New
See [CHANGELOG.md](CHANGELOG.md) for the full history.
**v1.2** adds smart write deduplication with LLM consultation, importance scoring with time-based decay and retrieval bumps, configurable similarity thresholds, and 6 new environment variables for the intelligence features.
**v1.1** adds semantic search with LanceDB, embedding providers (Ollama and fastembed), semantic chunking with configurable overlap, importance-weighted reranking, and a health endpoint that reports component status. Search works alongside CRUD — if embeddings aren't available, CRUD still works and search returns 503.
## Development
```bash
uv sync --extra dev
uv run pytest --cov=engram -v
```
Output: `276 passed` with `92.58%` coverage. The time varies by machine.
Lint and format:
```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```
