Engram

Persistent semantic memory layer for AI agents. Local-first storage (SQLite+LanceDB) with Ollama embeddings. Store and recall facts, decisions, preferences, events, relationships across sessions. Supports memory decay, deduplication, typed memories (5 types), memory relationships (7 graph relation types), agent/user scoping, semantic search, context-aware recall, auto-extraction from text (rules/LLM/hybrid), import/export, REST API, MCP protocol. Solves context window and compaction amnesia. Server at localhost:3400, dashboard at /dashboard. Install via npm (engram-memory), requires Ollama with nomic-embed-text model.

Security Scan

The skill's functionality (local semantic memory using an engram CLI + Ollama embeddings) is coherent, but the SKILL.md contains instructions and obligations that are not reflected in the metadata and that could cause sensitive data to be collected and persisted automatically — review before use.

Purpose & Capability

The described purpose (local semantic memory with embeddings, search, recall, REST API) matches the commands and features documented in SKILL.md (engram CLI, local server, Ollama embeddings). However, the platform metadata shown with the skill claims no required binaries or environment variables, while SKILL.md explicitly requires an 'engram' binary (npm package engram-memory) and Ollama + the nomic-embed-text model — an inconsistency in declared requirements and the runtime instructions. Source/homepage for the npm package is also missing, so the provenance of the engram CLI is unclear.

Instruction Scope

SKILL.md mandates a 'Boot Sequence (MANDATORY)': run `engram search "<current task context>"` on every session start, meaning the agent will automatically send session/task context to the local memory service. The docs also instruct auto-extraction from arbitrary text and explicitly list storing 'credentials' among storable facts. Those instructions can cause sensitive secrets and arbitrary context to be persisted into a local DB and served to agents later. While this is functionally consistent with a memory service, it is high-risk behavior if not tightly controlled (no automatic redaction/encryption described).

Install Mechanism

The skill is instruction-only (no install spec in platform), but SKILL.md instructs the user to install via npm (engram-memory), brew install ollama, and pull a model. These are standard package sources (npm, Homebrew, Ollama) rather than arbitrary URLs, which lowers technical risk. Caveats: the npm package and its provenance/homepage are not provided in the metadata; the brew command is macOS-specific and there is no Windows/Linux guidance; all installs are manual and would run code from third-party registries.

Credentials

The skill declares no required environment variables or primary credential, and SKILL.md primarily uses a local Ollama endpoint and optional 'openai' provider in config. That is proportionate for an embedding-backed memory layer. However, the instructions encourage storing arbitrary facts (including 'credentials' and other sensitive items) into local storage (~/.engram) and exposing them via a local REST API and dashboard. The absence of declared env/credential requirements is inconsistent with the risk of sensitive-data persistence and with the configuration paths mentioned in SKILL.md.

Persistence & Privilege

The skill is not marked always:true, but SKILL.md's 'MANDATORY' boot step asks the agent to run a search on every session start — effectively imposing persistent behavior (automatic queries and local server usage) without platform-level gating. The skill also instructs running a local server (http://localhost:3400) and dashboard. Combined with autonomous invocation (default), this increases the blast radius if secrets are stored or if the local server is misconfigured. The skill does not claim to modify other skills' configs, but the mandatory boot behavior is a scope-creep/privacy concern.

What to consider before installing

This skill appears to be a local-first memory layer and its commands/instructions align with that goal, but take these precautions before installing or enabling it: 1) Verify the provenance of the 'engram-memory' npm package (author, repository, checksum) and only install from a trusted source. 2) Be cautious about the SKILL.md 'MANDATORY' boot step — it instructs the agent to run an automatic search using the current task context on every session start; disable or modify this behavior if you do not want context automatically sent to the memory service. 3) Assume the system will persist anything you add (the docs explicitly mention storing 'credentials'); never ingest secrets or sensitive tokens unless you have encryption/audit controls and isolation in place. 4) Secure the local server/dashboard (localhost is safer than public host, but ensure it's bound to localhost only and access is restricted). 5) Consider using explicit retention/decay/deduplication settings and enable export/encryption of backups before allowing automated ingestion. 6) If you need higher assurance, request the upstream source code or a vetted package repository and a privacy/security whitepaper from the author; absence of a homepage/repository is a red flag. 7) If unsure, classify this as high-risk for sensitive contexts and run only in an isolated environment or container.

Engram: Persistent Memory for AI Agents

Engram gives you durable semantic memory that survives sessions, compaction, crashes. All local, no cloud, no token cost.

Boot Sequence (MANDATORY)

On every session start, run:

engram search "<current task context>" --limit 10

Example: engram search "client onboarding status churn risk" --limit 10

This recalls relevant memories from previous sessions before you start work.

Storing Memories

5 memory types: fact | decision | preference | event | relationship

# Facts — objective information
engram add "API rate limit is 100 req/min" --type fact --tags api,limits

# Decisions — choices made
engram add "We chose PostgreSQL over MongoDB for better ACID" --type decision --tags database

# Preferences — user/client likes/dislikes
engram add "Dr. Steph prefers text over calls" --type preference --tags dr-steph,communication

# Events — milestones, dates
engram add "Launched v2.0 on January 15, 2026" --type event --tags launch,milestone

# Relationships — people, roles, connections  
engram add "Mia is client manager, reports to Danny" --type relationship --tags team,roles

When to store:

• Client status changes (churn risk, upsell opportunity, complaints)
• Important decisions made about projects/clients
• Facts learned during work (credentials, preferences, dates)
• Milestones completed (onboarding steps, launches)

Searching

Semantic search (finds meaning, not just keywords):

# Basic search
engram search "database choice" --limit 5

# Filter by type
engram search "user preferences" --type preference --limit 10

# Filter by agent (see only your memories + global)
engram search "project status" --agent theo --limit 10

Context-Aware Recall

Recall ranks by: semantic similarity × recency × salience × access frequency

engram recall "Setting up new client deployment" --limit 10

Better than search when you need the most relevant memories for a specific context.

Memory Relationships

7 relation types: related_to | supports | contradicts | caused_by | supersedes | part_of | references

# Manual relation
engram relate <memory-id-1> <memory-id-2> --type supports

# Auto-detect relations via semantic similarity
engram auto-relate <memory-id>

# List relations for a memory
engram relations <memory-id>

Relations boost recall scoring — well-connected memories rank higher.

Auto-Extract from Text

Ingest extracts memories from raw text (rules-based by default, optionally LLM):

# From stdin
echo "Mia confirmed client is happy. We decided to upsell SEO." | engram ingest

# From command
engram extract "Sarah joined as CTO last Tuesday. Prefers async communication."

Uses memory types, tags, confidence scoring automatically.

Management

# Stats (memory count, types, storage size)
engram stats

# Export backup
engram export -o backup.json

# Import backup
engram import backup.json

# View specific memory
engram get <memory-id>

# Soft delete (preserves for audit)
engram forget <memory-id> --reason "outdated"

# Apply decay manually (usually runs daily automatically)
engram decay

Memory Decay

Inspired by biological memory:

• Every memory has salience (0.0 → 1.0)
• Daily decay: salience *= 0.99 (configurable)
• Accessing a memory boosts salience
• Low-salience memories fade from search results
• Nothing deleted — archived memories can be recovered

Agent Scoping

4 scope levels: global → agent → user → session

By default:

• Agents see their own memories + global memories
• --agent <agentId> filters to specific agent
• Scope isolation prevents memory bleed between agents

REST API

Server runs at http://localhost:3400 (start with engram serve).

# Add memory
curl -X POST http://localhost:3400/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "...", "type": "fact", "tags": ["x","y"]}'

# Search
curl "http://localhost:3400/api/memories/search?q=query&limit=5"

# Recall with context
curl -X POST http://localhost:3400/api/recall \
  -H "Content-Type: application/json" \
  -d '{"context": "...", "limit": 10}'

# Stats
curl http://localhost:3400/api/stats

Dashboard: http://localhost:3400/dashboard (visual search, browse, delete, export)

MCP Integration

Engram works as an MCP server. Add to your MCP client config:

{
  "mcpServers": {
    "engram": {
      "command": "engram-mcp"
    }
  }
}

MCP tools: engram_add, engram_search, engram_recall, engram_forget

Configuration

~/.engram/config.yaml:

storage:
  path: ~/.engram

embeddings:
  provider: ollama           # or "openai"
  model: nomic-embed-text
  ollama_url: http://localhost:11434

server:
  port: 3400
  host: localhost

decay:
  enabled: true
  rate: 0.99                 # 1% decay per day
  archive_threshold: 0.1

dedup:
  enabled: true
  threshold: 0.95            # cosine similarity for dedup

Best Practices

1. Boot with recall — Always engram search "<context>" --limit 10 at session start
2. Type everything — Use correct memory types for better recall ranking
3. Tag generously — Tags enable filtering and cross-referencing
4. Ingest conversations — Use engram ingest after important exchanges
5. Let decay work — Don't store trivial facts; let important memories naturally stay salient
6. Use relations — auto-relate after adding interconnected memories
7. Scope by agent — Keep agent memories separate for clean context

Troubleshooting

Server not running?

engram serve &
# or install as daemon: see ~/.engram/daemon/install.sh

Embeddings failing?

ollama pull nomic-embed-text
curl http://localhost:11434/api/tags  # verify Ollama running

Want to reset?

rm -rf ~/.engram/memories.db ~/.engram/vectors.lance
engram serve  # rebuilds from scratch

---

Created by: Danny Veiga (@dannyveigatx)
Source: https://github.com/Dannydvm/engram-memory
Docs: https://github.com/Dannydvm/engram-memory/blob/main/README.md