eidetic

README

Eidetic

Most AI agents are amnesiac. They forget everything between conversations. Eidetic fixes that.

Eidetic is a self-hosted semantic memory server for AI agents. Store memories, search them by meaning (not just keywords), and give your agents persistent context that survives across sessions, restarts, and even across different agents.

Built on PostgreSQL + pgvector + Ollama. Runs on CPU. No cloud required.

---

How it works

Agent A writes:                          Agent B searches:
"Deploy failed — rolled back v2.3"  ──▶  "What happened with the last deploy?"
                                         ──▶ Returns the rollback memory (0.87 similarity)

Every memory is:

1. Stored as a Markdown flat file (human-readable, grep-able, git-friendly)
2. Inserted into PostgreSQL with full-text search
3. Embedded asynchronously via Ollama (nomic-embed-text) into pgvector
4. Searchable by semantic similarity, keyword, agent, date range, or any combination

---

Works with

Client	Transport	Setup
Roger	HTTP/MCP	Native integration — just set eidetic.enabled: true
Claude Code	stdio	eidetic stdio as MCP server
Claude Desktop	stdio	Add to claude_desktop_config.json
Cursor / Windsurf	stdio	Same as Claude Desktop
OpenClaw	HTTP	Via custom skill
Any HTTP client	HTTP	POST /mcp with JSON-RPC

Roger config

{
  "eidetic": {
    "enabled": true,
    "baseURL": "http://localhost:7700",
    "apiKey": "your-key"
  }
}

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "eidetic": {
      "command": "/usr/bin/eidetic",
      "args": ["stdio"]
    }
  }
}

---

Install

From a release (recommended):

# Debian/Ubuntu
curl -LO https://github.com/EMSERO/eidetic/releases/latest/download/eidetic_0.4.0_linux_amd64.deb
sudo dpkg -i eidetic_0.4.0_linux_amd64.deb

# Or download a tarball from
# https://github.com/EMSERO/eidetic/releases

From source:

git clone https://github.com/EMSERO/eidetic.git
cd eidetic
go build -o eidetic ./cmd/eidetic

Requires Go 1.26+, PostgreSQL 15+ with pgvector, and Ollama.

---

Quick start

# Configure
mkdir -p ~/.eidetic
cp docs/config.example.yaml ~/.eidetic/config.yaml
# Edit: set auth.api_key and postgres.dsn

# Run (migrations apply automatically on startup)
eidetic serve

# As a systemd service
systemctl --user enable --now eidetic

Docker

EIDETIC_API_KEY=your-key docker compose up

Starts Postgres+pgvector, Ollama, and Eidetic. Everything auto-configures.

---

MCP Tools

Tool	Description
append_memory	Write a new entry (flat file + Postgres + async embedding)
search_memory	Semantic search with cosine similarity; filters: agent_id, date range, keyword, metadata
get_recent	Most recent entries, optional agent filter

---

Features

• Semantic search — pgvector cosine similarity finds relevant memories by meaning
• Hybrid search — combines vector similarity with full-text ranking (Reciprocal Rank Fusion)
• Flat-file backup — every memory is also a Markdown file on disk
• Value gate — optional LLM-powered filter rejects low-value entries at ingestion
• Content fingerprinting — SHA-256 deduplication prevents the same content being stored twice
• Auto-migrate — database schema migrations run automatically on startup (v0.4.0+)
• CPU-friendly — nomic-embed-text via Ollama runs on CPU; no GPU needed
• Extension system — process entries through custom extension pipelines

---

CLI

eidetic serve                    # Start HTTP MCP server (default: localhost:7700)
eidetic stdio                    # Start in stdio mode for local MCP clients
eidetic reindex [--yes]          # Rebuild Postgres from flat files
eidetic archive                  # Gzip files older than archive_after_days
eidetic prune                    # Remove low-value entries using value gate

---

Configuration

See docs/config.example.yaml for a complete template.

Environment variable overrides:

• EIDETIC_API_KEY — auth.api_key
• EIDETIC_POSTGRES_DSN — postgres.dsn
• EIDETIC_OLLAMA_HOST — ollama.host

Send SIGHUP to reload config without restarting.

---

Health

GET /health — returns status: ok (200) or status: degraded (503). No auth required on loopback.

---

License

MIT

---

Inspired in part by Nate B Jones and his work on AI agents and autonomous workflows.

Built by EMSERO — software engineering for defense, federal, and commercial systems.