AutoGineer
Generated banner for AutoMem
Generated logo for AutoMem

AutoMem

Memory framework

First committed by jack-arturo

Published in verygoodplugins/automem. Publisher page

827 GitHub stars

What it is

Long-term memory for AI assistants. Graph + vector store that recalls decisions, relationships, and context across sessions.
— the description by jack-arturo

AutoGineer overview, from the brain’s own files

AutoMem is a memory service designed to provide AI assistants with persistent, long-term recall. By combining a graph database (FalkorDB) for structured relationships and a vector database (Qdrant) for semantic search, it enables agents to retrieve not just similar snippets, but the context and reasoning behind past decisions. It supports a wide range of AI tools via the Model Context Protocol (MCP) and a REST API, allowing a single memory store to be shared across multiple platforms like Claude, Cursor, and GitHub Copilot. The system includes automated consolidation cycles to manage memory relevance and importance over time, ensuring that the agent's knowledge base remains efficient as history grows.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

AutoMem operates as a service with two primary storage layers: FalkorDB for storing memories as nodes with typed relationships, and Qdrant for storing vector embeddings. When an AI client requests a recall, the system performs a hybrid query that combines semantic similarity, graph traversal, and temporal alignment to rank results. A background enrichment pipeline and consolidation engine process memories to maintain relevance, while the MCP bridge allows various AI agents to interact with the memory service locally or remotely.

Folders
FolderRoleFiles
.githubagent-config9
docsdocs18
scriptsscripts39
teststests78
.railwayfolder2
automemfolder70
benchmarksfolder9
mcp-sse-serverfolder14

The agent reads

The agent writes

Requirements

Runtimes: Python

Databases: FalkorDB, MongoDB, PostgreSQL, Qdrant, Redis, SQLite

API keys (by name): ADMIN_API_TOKEN, AUTOMEM_API_TOKEN, AUTOMEM_TEST_ADMIN_TOKEN, AUTOMEM_TEST_API_TOKEN, CLASSIFICATION_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, QDRANT_API_KEY, VOYAGE_API_KEY

Works with: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Kiro, OpenCode, Amp, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 1 script. Review Makefile before opening the folder in Claude Code. No step below turns a hook on for you.

    • Makefile: echo "🔧 Setting up development environment..."; bash scripts/bootstrap_dev.sh; echo "✅ Virtual environment ready!"; echo "💡 Run 'source .venv/bin/activate' to activate"
  2. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/verygoodplugins/automem/blob/1a7ba1a6afe69835f62ad7f6013e33301d1ab83e/README.md#run-it

  3. First committed by jack-arturo. Published in verygoodplugins/automem. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Connect local AI tools like Claude Desktop or Cursor to the AutoMem service via the MCP bridge.
  • Use the REST API to programmatically store decisions, preferences, and project context.
  • Query the memory service to retrieve the reasoning behind past technical choices or project milestones.
  • Deploy the memory service on local infrastructure or cloud platforms like Railway for persistent agent access.
“Why did we choose PostgreSQL?”
The agent retrieves the decision node, the rationale, and the considered alternatives, providing the context behind the architectural choice.
“What are our current preferences for message queues?”
The agent traverses the graph to identify the relationship between Kafka and RabbitMQ, surfacing the team's preference for 'boring technology'.

Documentation by jack-arturo

<p align="center"> <img src="https://automem.ai/img/G_Vd7EYWYAM_3SF.jpeg" alt="AutoMem" width="600" /> </p>

<p align="center"> <a href="https://www.npmjs.com/package/@verygoodplugins/mcp-automem"><img src="https://img.shields.io/npm/v/@verygoodplugins/mcp-automem?label=mcp-automem" alt="npm version" /></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/verygoodplugins/automem" alt="License" /></a> <a href="https://automem.ai/discord"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a> <a href="https://x.com/automem_ai"><img src="https://img.shields.io/badge/X-@automem__ai-000000?logo=x&logoColor=white" alt="X" /></a> <a href="https://automem.ai/benchmarks"><img src="https://img.shields.io/badge/LoCoMo%20(AMB)-85.1%25-success" alt="LoCoMo on the neutral Agent Memory Benchmark" /></a> <a href="benchmarks/EXPERIMENT_LOG.md#results"><img src="https://img.shields.io/badge/LongMemEval%20full-87.0%25-blueviolet" alt="LongMemEval full on AutoMem's internal harness: 87.0%" /></a> <a href="https://automem.ai/benchmarks"><img src="https://img.shields.io/badge/BEAM%2010M%20(AMB)-57.4%25-success" alt="BEAM 10M on the neutral Agent Memory Benchmark" /></a> <a href="https://railway.com/deploy/automem-ai-memory-service?referralCode=VuFE6g&utm_medium=integration&utm_source=github&utm_campaign=generic"><img src="https://img.shields.io/badge/Deploy%20on-Railway-0B0D0E?logo=railway&logoColor=white" alt="Deploy on Railway" /></a> </p>

<p align="center"> <strong>Long-term memory for AI assistants — fast, private, and yours.</strong> </p>

AutoMem

AutoMem gives your AI a memory that survives the chat.

Save the decisions, preferences, notes, and context that matter. The next time you open Claude, Cursor, Codex, ChatGPT, or another connected assistant, it can bring back the right details instead of making you repeat yourself.

Ask, “Why did we choose PostgreSQL?” and AutoMem can return the decision, the alternatives you considered, the principle behind it, and the work that followed — not just a pile of similarly worded snippets.

Why AutoMem feels different

No LLM call in the middle of recall. AutoMem looks up memories directly through its graph and vector index. That keeps normal retrieval fast and avoids an extra generative-LLM charge every time your assistant needs context. It still uses embeddings — from Voyage, OpenAI, or a local provider — and optional enrichment can add more structure over time.

More than vector search. A vector match finds something similar; AutoMem also records typed relationships between memories. It can follow the connections between a decision, its rationale, and its consequences, so your assistant has a better chance of returning the why, not only the words it recognizes.

One memory across your tools. Use the local MCP bridge with Claude Desktop, Cursor, Claude Code, Codex, Copilot, and more. For cloud agents, Remote MCP connects the same service to ChatGPT Developer Mode, Claude.ai, and ElevenLabs over HTTPS. Your memory is not locked to one chat app.

Own the data and the setup. Run AutoMem locally with Docker, on your own infrastructure, or as a small Railway service group. It exposes both MCP and a REST API, so it fits into the tools and workflows you already use.

Proven where long context gets hard

On the independent Agent Memory Benchmark's BEAM long-context tests, AutoMem scored 57.4% at 10 million source tokens while giving the answerer an average of only ~2.6–4.8k retrieved tokens. That is the kind of efficiency that lets memory stay useful as an agent's history grows.

The full picture — test setup, raw outputs, methodology, historical runs, and reproduction commands — is in automem.ai/benchmarks and benchmarks/EXPERIMENT_LOG.md.

How it works

AutoMem combines two storage layers behind a single API:

  • FalkorDB stores memories as nodes with 11 typed relationships between them. The graph is the canonical record.

  • Qdrant stores an embedding for every memory. Recall is a hybrid query — semantic similarity, graph traversal, temporal alignment, tag overlap, and importance — ranked by a 9-component score.

flowchart TB
    subgraph service [AutoMem Service Flask]
        API[REST API<br/>Memory Lifecycle]
        Enrichment[Background Enrichment<br/>Pipeline]
        Consolidation[Consolidation<br/>Engine]
        Backups[Automated Backups<br/>Optional]
    end

    subgraph storage [Dual Storage Layer]
        FalkorDB[(FalkorDB<br/>Graph Database)]
        Qdrant[(Qdrant<br/>Vector Database)]
    end

    Client[AI Client] -->|Store/Recall/Associate| API
    API --> FalkorDB
    API --> Qdrant
    Enrichment -->|11 edge types<br/>Pattern nodes| FalkorDB
    Enrichment -->|Semantic search<br/>1024-d vectors| Qdrant
    Consolidation --> FalkorDB
    Consolidation --> Qdrant
    Backups -.->|Optional| FalkorDB
    Backups -.->|Optional| Qdrant

If Qdrant is unavailable, the graph still serves recall in a degraded mode. If FalkorDB is down, the API returns 503 — the graph is the source of truth.

Multi-hop bridge discovery

Ask "why boring tech for Kafka?" and AutoMem doesn't just match the word "Kafka". It traverses the graph from the seed memories to find the bridge that connects them:

  • Seed 1: "Migrated to PostgreSQL for operational simplicity"

  • Seed 2: "Evaluating Kafka vs RabbitMQ for message queue"

  • Bridge: "Team prefers boring technology — proven, debuggable systems"

Both seeds carry an EXEMPLIFIES edge to the bridge memory. AutoMem ranks the bridge above the seeds and surfaces it in the recall response, so the assistant answers with your reasoning, not isolated facts. Tune via expand_relations, relation_limit, and expansion_limit on GET /recall.

11 authorable relationship types
TypeUse caseExample
RELATES_TOGeneral connectionBug report → Related issue
LEADS_TOCausal relationshipProblem → Solution
OCCURRED_BEFORETemporal sequencePlanning → Execution
PREFERS_OVERUser preferencesPostgreSQL → MongoDB
EXEMPLIFIESPattern examplesCode review → Best practice
CONTRADICTSConflicting infoOld approach → New approach
REINFORCESSupporting evidenceDecision → Validation
INVALIDATED_BYOutdated infoLegacy docs → Current docs
EVOLVED_INTOKnowledge evolutionInitial design → Final design
DERIVED_FROMSource trackingImplementation → Spec
PART_OFHierarchical structureFeature → Epic

Three more edge types are added automatically by the enrichment pipeline and consolidation engine: SIMILAR_TO, PRECEDED_BY, and DISCOVERED.

Memory consolidation, neuroscience-inspired

AutoMem implements biological memory consolidation cycles. Wrong rabbit holes fade naturally. Important memories with strong connections strengthen over time.

CycleFrequencyPurpose
DecayDailyExponential relevance scoring (age, access, connections, importance)
CreativeWeeklyREM-like processing that discovers non-obvious connections
ClusterMonthlyGroups similar memories, generates meta-patterns
ForgetOff by defaultArchives low-relevance memories (<0.2), deletes very old (<0.05)

Tune intervals via CONSOLIDATION_*_INTERVAL_SECONDS. See docs/ENVIRONMENT_VARIABLES.md.

For more on the recall scoring formula, enrichment internals, and how AutoMem differs from RAG and pure vector databases, see docs/COMPARISON.md.

Research foundation

AutoMem implements techniques from peer-reviewed memory research:

  • HippoRAG 2 (Ohio State, 2025) — graph + vector hybrid for associative memory

  • A-MEM (2025) — Zettelkasten-inspired dynamic memory organization

  • MELODI (DeepMind, 2024) — gist-based memory compression

  • ReadAgent (DeepMind, 2024) — episodic memory for context extension

Full writeups, findings, and how AutoMem implements each → docs/RESEARCH.md.

Run it

Railway (60 seconds)

Image: Deploy on Railway

Recommended Railway projects run AutoMem as a small service group: automem (the API), automem-graph-viewer (the standalone UI), falkordb (graph), qdrant (vectors), and mcp-automem (the MCP bridge for ChatGPT, Claude.ai, and ElevenLabs). Services use pre-built Docker images and auto-redeploy on :stable, so Railway does not spend compute rebuilding source.

→ Full setup: INSTALLATION.md

Docker Compose (local)
git clone https://github.com/verygoodplugins/automem.git
cd automem
make dev
ServiceURLPurpose
AutoMem APIhttp://localhost:8001Memory REST API
FalkorDBlocalhost:6379Graph database
Qdrantlocalhost:6333Vector database
FalkorDB Browserhttp://localhost:3000Local graph inspection UI

Database and browser ports bind to localhost by default; the API binding is unchanged.

→ Full setup: INSTALLATION.md

Python (development)
make install
source .venv/bin/activate
PORT=8001 python app.py

Requires Python 3.10+ (3.12 recommended). → INSTALLATION.md

Contributing: feature PRs target the develop branch. main only moves via validated release merges, so users deploying from main (e.g. Railway auto-deploys) see one deploy per release instead of one per PR.

Connect your AI

ClientModeSetup
Claude Desktop, Cursor, Claude Code, Codex, Copilot, AntigravityLocal MCP bridgenpx @verygoodplugins/mcp-automem setup
ChatGPT (developer mode), Claude.ai web/mobile, ElevenLabs AgentsRemote MCP (HTTPS)docs/MCP_SSE.md
Anything elseDirect REST APIdocs/API.md

The MCP bridge is published as @verygoodplugins/mcp-automem. It handles client-specific config (rules files, hooks, templates) and proxies to your AutoMem service — local or Railway.

Direct API call:

import requests

token = "your-automem-api-token"

requests.post(
    "https://your-automem.railway.app/memory",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "content": "Chose PostgreSQL over MongoDB for ACID compliance",
        "type": "Decision",
        "tags": ["database", "architecture"],
        "importance": 0.9,
    },
)

Screenshots

<!-- CAPTURE CHECKLIST — replace each placeholder image once captured: 1. docs/img/graph-recall.png — FalkorDB browser at http://localhost:3000 showing a memory node with multiple typed edges visible (PREFERS_OVER, EXEMPLIFIES, RELATES_TO). Proves the graph is real. 2. docs/img/claude-recall.png — Claude Desktop conversation where the assistant cites a recalled memory inline, with the AutoMem MCP tool call visible in the trace. 3. docs/img/railway-services.png — Railway dashboard showing the production service group (automem, automem-graph-viewer, mcp-automem, qdrant, falkordb). A version exists as a GitHub user-attachment in INSTALLATION.md; capture a clean version and host it in-repo. Until each PNG exists, the table cells will render as broken-image icons on GitHub. -->

Screenshots will be added once the referenced in-repo image assets are available.

Known limitations

AutoMem is pre-1.0 and honest about its rough edges. The active ones for recall quality:

  • Tags are a hard gate, not a soft boost. Tags filter before scoring, so a memory missing the queried tag won't surface even on a perfect semantic match. Within a tag scope, high-importance off-topic memories can still over-rank — mitigated by the opt-in RECALL_RELEVANCE_GATE, not yet on by default (#130).

  • Temporal and preference updates. Recall doesn't yet reliably prefer the newest version of a conflicting fact, or fully resolve multi-session preference updates. The RECALL_RECENCY_BIAS=auto re-rank helps temporal-intent queries but stays opt-in pending broader validation (#158, #159).

  • The MCP SSE bridge doesn't forward state_mode. The HTTP recall API supports it; the SSE proxy doesn't pass it through yet (#172).

  • Entity-node synthesis is experimental and off by default. First-class Entity nodes (IDENTITY_SYNTHESIS_ENABLED) are gated off while people-entity word-pair noise is addressed (#181).

Docs, community, and license

Setup

API and integration

  • API reference — endpoints, scoring, enrichment

  • Remote MCP — ChatGPT, Claude.ai, ElevenLabs

  • Migrations — embedding dimensions, 0.16.0 data migrations, MCP SQLite import

Research and comparison

Operations

Community

Sibling repos

MIT licensed. Deploy anywhere. No vendor lock-in.

CHANGELOG.md

Changelog

All notable changes to AutoMem will be documented in this file.

0.16.2 (2026-08-28)

Bug Fixes

  • backup: page FalkorDB export by node id instead of deep SKIP (#221) (009d58e)

  • config: preserve Ollama defaults and migration checks (0bc0096)

  • docs: complete embedding migration runbooks (3468443)

  • docs: correct re-embedding migration setup (a8be394)

  • enrichment: circuit-break exhausted quota calls (ea148e5)

  • enrichment: circuit-break exhausted quota calls (#229) (ad3ed27)

  • enrichment: preserve quota circuit during in-flight calls (29f359d)

  • mcp-sse: emit the stored date in compact recall output (#224) (42ba8b6)

  • mcp: align the parity harness with its own allowlist (9ac5b4e)

  • mcp: close false-failure and coverage gaps in the parity harness (4cf9ef1)

  • mcp: close partial connections when parity setup fails (89346e9)

  • mcp: isolate parity fixtures per scenario and drop the false alarm (fa458b0)

  • qdrant: index the type payload field so recall filters stop 400ing (c131f02)

  • qdrant: index the type payload field so recall filters stop 400ing (#223) (10bcac7)

  • recovery: honor configured graph and cloud migrations (4dd1325)

  • stream: emit live memory operations on GET /stream (#227) (7a92ebd)

Performance Improvements

  • qdrant: store collection data on disk (#231) (07d8704)

  • qdrant: store new collection data on disk (c97b5b1)

  • qdrant: support disk-backed HNSW restores (b04b9e1)

Documentation

  • add Qdrant on-disk implementation plan (56da2b7)

  • add Qdrant on-disk storage design (e177b60)

  • align provider and maintenance guidance (93afcff)

  • align provider and maintenance guidance (#232) (c40d1d2)

  • enrichment: document quota circuit (d9787cb)

  • mcp: audit remote vs stdio transport parity (92b98ec)

  • qdrant: add on-disk migration runbook (d05a2d9)

  • qdrant: harden on-disk migration runbook (db71f07)

  • qdrant: limit migration to default topology (9b31cde)

  • qdrant: verify migration export before restore (45e77f4)

  • readme: lead benchmark section with neutral AMB numbers (#219) (8ff266e)

  • target feature PRs at develop (#228) (bcef376)

0.16.1 (2026-07-07)

Bug Fixes

  • api: reject admin placeholder fallback (69d8205)

  • api: reject placeholder provider repairs (d2ce087)

  • api: use provider embeddings for admin repair (b636b50)

  • api: use provider embeddings for admin repair (#211) (3ae04bf), closes #208

  • memory: require confirmed graph writes (878e638)

  • memory: require confirmed graph writes (#216) (57264a9)

  • recall: address Codex artifact review feedback (860e0e7)

  • recall: address Codex overfetch follow-ups (d18d5d7)

  • recall: over-fetch vector candidates and exclude artifact types (ddc9ecc)

  • recall: over-fetch vector candidates and exclude artifact types (#205) (0720da2)

  • recall: preserve metadata sidecar budget (b9d89c2)

  • recall: preserve metadata sidecar upgrades (ed3c188)

  • recall: preserve vector fetch limit floor (833cbbb)

  • recall: widen context tag candidate fetch (a29e9fb)

  • recall: widen context tag candidate fetch (#215) (01e1082)

  • sync: ignore metapattern artifacts in drift checks (cd6f07d)

  • sync: ignore metapattern artifacts in drift checks (#214) (7636021), closes #209

Documentation

0.16.0 (2026-06-26)

Features

  • api: add admin backup endpoint (#162) (8b1f264)

  • api: support bulk memory associations (1221e36)

  • api: support bulk memory associations (#198) (28eb916)

  • benchmarks: LongMemEval failure-mode diagnosis harness + judge quota preflight (#183) (f99bece)

  • consolidation: expose cluster threshold and min size as env vars (#163) (7e731f3)

  • enrichment: expose classification fallback-rate metrics in /enrichment/status (#188) (0b522a9)

  • entity: harden identity cleanup and repair tooling (#176) (827dfbc)

  • eval: recall-quality optimization harness — lab foundation + design (#197) (431433e)

  • graph: support unbounded visualizer snapshots (#141) (c730128)

  • lab: add aged labelled distractor injection (cc5d546)

  • lab: add config_complexity simplicity metric (dfb10d9)

  • lab: add distractor_rate_at_k precision guardrail metric (872eab2)

  • lab: add lab_corpus with parameterized recall (5e1e071)

  • lab: add pick_winner scorecard decision rule (3187eac)

  • lab: add real consolidation pass helper (48a7d4a)

  • lab: isolate production clone restores (#171) (aef90c0)

  • lab: wire scorecard, distractors, recall params, consolidation into runner (589ec30)

  • recall: add metadata sidecar search (#177) (4e7956e)

  • recall: add state_mode=current|history recall alias (#173) (b1df86c)

  • recall: cap tag-score denominator to fix query-length bias (#193) (cefa516)

  • recall: date-aware ranking + latest-fact selection (#158, #159) (#187) (a6ed945)

  • recall: make recency decay window and curve configurable (#182) (dbb933f)

  • recall: ranking release — recency config, tag-score cap, relevance gate, date-aware ranking (#182, #193, #186, #187, #183, #184, #188) (#194) (337fe98)

  • scripts: safer reclassify_with_llm.py with provider flags + tighter prompt (#164) (a742602)

Bug Fixes

  • api: address copilot review on PR #198 (0466a1e)

  • api: handle grouped association write failures (cd93df9)

  • backup: make backup_automem.py runnable as python scripts/backup_automem.py (#175) (edd9742)

  • benchmarks: add publication verification bundle (#166) (420d721)

  • consolidation: skip eager first tick at startup to avoid FalkorDB load race (#165) (1b812cf)

  • docs: keep dispatch payload arrays stable (df6e9e8)

  • embedding: fall back to per-item real embeddings before placeholders in batch path (#189) (6e9c62c)

  • entity: restore person-shape exemption on the slug validation path (#179) (5e29960)

  • entity: stop validator over-rejecting real people, code tools, and event categories (#178) (193b730)

  • lab: address copilot review on PR #197 (45f80d6)

  • lab: align scorecard key contract (build_scorecard -> pick_winner) (7d91530)

  • mcp-sse: decouple /health liveness from upstream readiness (#151) (5bcfb8b)

  • mcp: cap association failure summary (ea4e08f)

  • mcp: surface stored metadata and updated_at in detailed recall format (#184) (230416e)

  • recall: address copilot review on PR #194 (50b1647)

  • recall: canonicalize / and : separators in context_tag matching (3afd9d3)

  • recall: canonicalize / and : separators in context_tag matching (#203) (ba5e9ff)

  • recall: gate query-independent scoring on topical evidence within tag scope (#130) (#186) (c11b594)

  • recall: hydrate semantic recall summaries (#192) (76e845d)

  • recall: normalize graph keyword scores into the 0-1 component range (#191) (3653ddf)

  • recall: respect current memory state (#170) (ed36b98), closes #169 #158 #159

  • scripts: add sys.path guard to reembed_embeddings.py (d333cf0)

Documentation

  • add scripts catalog, recall-quality-lab guide, and 0.16.0 migrations (f20c664)

  • bench: log full judged 500q LongMemEval ship-config run with churn attribution (41bf8d0)

  • eval: Plan A — lab metric foundation (TDD, 9 tasks) (0087dda)

  • eval: Plan B — parallel matrix harness (TDD, 9 tasks) (c8ddfb2)

  • evals: mark Memora/FAMA/WRIT lifecycle diagnostics as diagnostic-only (#174) (e8a3285)

  • eval: spec for recall-quality optimization harness (b1a1995)

  • fix stale claims and document gated flags for 0.16.0 (b152d64)

  • note develop-branch contribution policy in README (ccf02dd)

  • positioning: add scout reference (#168) (922d23b)

  • refresh benchmark currency for the neutral AMB run and prune stale archive docs (3ff95bd)

  • refresh benchmark currency for the neutral AMB run and prune stale archive docs (#204) (89c30e0)

  • refresh README and benchmark guidance (#157) (bba31cc)

  • runtime: align Docker viewer paths and setup guidance (#155) (bbda79b)

  • scripts catalog, recall quality lab guide, and 0.16.0 migration runbook (#199) (f190ae5)

0.15.2 (2026-04-23)

Bug Fixes

  • benchmarks: make LoCoMo judge runs reliable (#149) (c22f2c9)

  • recall: bypass tag filter on expansion candidates (#142) (#146) (4f0fcf8)

  • recall: keyword scoring for vector results + softer adaptive floor (#150) (591b2c7)

0.15.1 (2026-03-25)

Bug Fixes

  • consolidation: fetch cluster/creative embeddings from Qdrant (#131) (96d0660)

  • embedding: validate provider dimension compatibility before init (#134) (9ac2fb2)

  • runtime: support OPENAI_BASE_URL for classification client (#135) (95a58c9)

0.15.0 (2026-03-12)

Features
Bug Fixes

  • benchmarks: correct evaluator bugs, add agent guidelines, establish honest baseline (#117) (d9cbecb)

  • recall: priority_ids parameter only boosts relevance (#79) (#125) (5d3708c)

0.14.0 (2026-03-07)

Features

  • config: add QDRANT_HOST + QDRANT_PORT as alternative to QDRANT_URL (#112) (0871904)

  • docker: Add Docker build workflow (#98) (39bf6e7)

Bug Fixes

  • benchmarks: handle possessive speaker names in LoCoMo (#116) (abcbcca)

  • consolidation: reduce decay rate, add importance floor, filter archived memories (#78) (#105) (3fce4ce)

  • handle smart apostrophes in recall entity extraction (#115) (05b4daa)

  • harden MCP bridge resilience, adopt stateless transport, and update cross-client docs (#114) (ec88da6)

  • qdrant: prevent silent vector dimension mismatch, set Voyage as recommended default (#108) (5f88105)

0.13.0 (2026-03-02)

Features

  • bench: benchmark testing infrastructure for rapid iteration (#97) (80a6f93)

  • recall: add min_score threshold and adaptive floor filtering (#73) (#101) (8df3c08)

  • viewer: add standalone graph-viewer runtime files (5bcb6db)

  • viewer: consolidate stable core and split-ready compatibility (#94) (958da72)

  • viewer: externalize visualizer with /viewer compatibility routes (29bafcf)

  • viewer: merge visualizer stable core branch (96b27bf)

Bug Fixes
Documentation

0.12.0 (2026-02-20)

Features

  • add LongMemEval benchmark harness (ICLR 2025) (#83) (8f51895)

  • just-in-time enrichment on recall (#86) (#88) (743ab6b)

  • lab: add Recall Quality Lab for data-driven recall optimization (d53dfdd)

  • lab: Recall Quality Lab + fix relevance_score Qdrant sync (#81) (ba1308a)

Bug Fixes

  • code quality improvements from CodeRabbit review (#85) (4c81f0f)

  • lab: address CodeRabbit review — type hints, f-strings, validation (5fee1e8)

  • lab: address CodeRabbit review findings (c121341)

  • recall: sync relevance_score to Qdrant payload for vector search (55e381b)

Documentation

  • Update environment variables (08e6126)

0.11.0 (2026-02-16)

Features

  • api: add GET /memory/<id> endpoint (9625580)

  • api: add GET /memory/<id> endpoint (#68) (205bdbe)

  • embedding: add Voyage AI embedding provider (a2ca403)

  • embedding: add Voyage AI embedding provider (#67) (1bafc44)

  • embedding: support OpenAI-compatible providers via OPENAI_BASE_URL (#76) (383a798), closes #70

Bug Fixes

  • add defensive validation and improve error handling in Voyage provider (4c8433a)

  • add httpx to prod deps, skip retry on ValueError, validate embedding count (95c1e9d)

  • add missing metadata parsing and access tracking to GET /memory/<id> (d115929)

  • guard against bool values in numeric timestamp parsing (2304c5c)

  • utils: handle numeric timestamps and non-string values in time parser (0bb222b)

  • utils: handle numeric timestamps and non-string values in time parser (#69) (2ba2931)

  • validate embedding items and fix line length (4c0d278)

Documentation

  • api: include 500 error for GET /memory/{id} (4b5a603)

0.10.1 (2026-02-07)

Bug Fixes

  • bound temporal query to 7-day window with timeout (#62) (9c720de)

  • skip temperature param for o-series and gpt-5 models (#65) (f1d5b1d)

  • use max_completion_tokens for gpt-5 model family (#61) (1ec25db)

0.10.0 (2026-02-06)

Features

  • Add exclude_tags parameter to recall API (#58) (8aeca2e)

  • add memory content size governance with auto-summarization (e24a86b)

  • add memory content size governance with auto-summarization (876aabf)

  • Add real-time observability with SSE streaming and TUI monitor (54d2701)

  • Add real-time observability with SSE streaming and TUI monitor (c5f6370)

  • Add real-time observability with SSE streaming and TUI monitor (944168e)

  • api: add graph visualization API endpoints (#26) (a0d0dd3)

  • api: add time-based sorting to recall API (c063845)

  • api: add time-based sorting to recall API (a511f0c)

  • create coderabbit.yml (e05811f)

  • embedding: add Ollama embedding provider and expand docs (#56) (b506a90)

  • mcp-sse: agent-friendly recall output + tests (71201d3)

  • mcp-sse: improve recall tool output and options (97c4f72)

Bug Fixes

  • Add TTL cleanup to InMemoryEventStore (0631af6)

  • Address CodeRabbit security and lint issues (a701c57)

  • backup: Fix GitHub Actions backup failing with connection error (19ed1e8)

  • backup: Fix GitHub Actions backup failing with connection error (10b37d0)

  • consolidation: prevent accidental forgetting (4330c20)

  • consolidation: prevent accidental forgetting (39dee3e)

  • Correct token parameter for gpt-5 models (max_output_tokens) (0786705)

  • enrichment: sync tags/tag_prefixes to Qdrant (3ccf874)

  • enrichment: sync tags/tag_prefixes to Qdrant (7ba9d76)

  • Handle streamable HTTP client disconnects (f15a7ee)

  • mcp-sse: update test for SDK 1.20+ Accept header behavior (597909e)

  • mcp: close transport/server on sweep and update Accept header test (ce7f6fa)

  • mcp: replace broken res.on('close') with TTL sweep for Streamable HTTP sessions (3d53263)

  • mcp: replace broken res.on('close') with TTL sweep for Streamable HTTP sessions (#59) (d4d3259)

  • mcp: use Promise.resolve().catch() for async close() in session sweep (a8cc589)

  • Production bugs - datetime tz, OpenAI tokens, Qdrant race (14491c4)

  • Production bugs - datetime tz, OpenAI tokens, Qdrant race (0771360)

  • Refactor tests to use double quotes for consistency (21da453)

  • Refine summarization token limit and improve tests (6cab145)

  • Update test for POST /mcp Accept header error (67a5a10)

  • YAML indentation in backup workflow and update docs (a606b3e)

Documentation

  • add mermaid diagrams for architecture visualization (0d70a2a)

  • Add Qdrant setup guide and update docs for AUTOMEM_API_URL (5c440aa)

  • Add Qdrant setup guide and update docs for AUTOMEM_API_URL (123ff28)

  • Enhance README.md with formatted NPM bridge link (09ac4ac)

  • merge mermaid diagrams from docs/add-mermaid-diagrams (4e9ae4f)

  • Update API documentation and configuration settings (9281149)

  • Update API documentation and configuration settings (#51) (ad9500f)

  • Update API endpoint count and project description (9e71299)

  • update diagrams for Streamable HTTP transport (1a2ce22)

  • Update docs to clarify MCP bridge and improve formatting (af69a2f)

  • Update MCP documentation and server implementation for Streamable HTTP support (8fdef09)

  • Update MCP documentation and server implementation for Streamable HTTP support (335a78d)

  • update MCP_SSE.md to reflect MCP bridge terminology (940a776)

  • Update Railway deployment docs and improve README (5480eb5)

  • Update Railway deployment docs and improve README (82c33b0)

[Unreleased]

Fixed

  • GitHub Actions Backup: Fixed backup workflow failing with "Connection reset by peer" error

    • Root cause: Backup script tried to connect to Railway internal hostname which isn't accessible from GitHub Actions

    • Solution: Use Railway TCP Proxy for external access to FalkorDB

    • Added pre-flight connectivity check with clear error messages and troubleshooting guidance

    • Updated documentation with TCP Proxy setup instructions

Documentation

  • Expanded docs/MONITORING_AND_BACKUPS.md with:

    • TCP Proxy setup instructions for GitHub Actions backups

    • Network architecture diagram explaining internal vs external access

    • Troubleshooting section for common backup failures

    • Debug checklist for verifying backup configuration

[0.9.3] - 2025-12-10

Fixed

  • Critical: Fixed missing RECALL_EXPANSION_LIMIT import that caused crashes when using expansion features

CI/CD

  • Added GitHub Actions CI workflow with tests on Python 3.10, 3.11, 3.12

  • Added pre-commit hooks for code quality enforcement

    • Black formatting (100 char line length)

    • isort import sorting

    • Flake8 syntax checking

    • Conventional commit validation

    • Secret detection

  • Added release-please for automated versioning and releases

Style

  • Applied consistent formatting across entire codebase with Black and isort

[0.9.2] - 2025-12-10

Added

  • Expansion Filtering: Added expand_min_strength and expand_min_importance parameters to recall API

    • Filters expanded relation results by connection strength and target memory importance

    • Reduces noise in multi-hop reasoning and graph expansion

    • Seed results are never filtered, only expanded memories

    • Recommended values: 0.3-0.5 for broad context, 0.6+ for focused results

  • Vector Dimension Autodetect: Added VECTOR_SIZE_AUTODETECT env var

    • Automatically detects and adopts existing Qdrant collection dimension

    • Prevents service crashes when upgrading defaults (e.g. 768d -> 3072d)

Documentation

  • Expanded docs/API.md with detailed expansion filtering documentation and examples

  • Added graph expansion examples to README.md API examples section

[0.9.1] - 2025-12-02

🏆 Benchmark Improvement

  • Achieved 90.53% on LoCoMo-10 (SOTA, +2.29pp over CORE at 88.24%)

  • Multi-hop reasoning improved from 37.5% to 50% (+12.5pp)

  • New benchmark report: tests/benchmarks/BENCHMARK_2025-12-02.md

🔗 Entity-to-Entity Expansion

  • Feature: New expand_entities parameter for multi-hop reasoning via entity tags

  • How it works: Extracts entities from seed results → searches for entity:people:{name} tags

  • Use case: Query about "Amanda's sister's career" finds "Amanda's sister is Rachel" → entity expansion finds "Rachel works as counselor"

  • Respects original tag filters for proper context scoping

🧪 Test Infrastructure

  • Fixed test cleanup: was missing 99% of tagged memories (used wrong endpoint)

  • Added test_multihop_quick.py for rapid multi-hop iteration

  • Improved Q+A embedding similarity checking in test harness

📝 Documentation

  • Updated API.md with expand_entities and expand_relations params

  • Updated ENVIRONMENT_VARIABLES.md with RECALL_EXPANSION_LIMIT

  • Updated TESTING.md with latest benchmark results

  • Updated README with 90.53% score

🔧 Configuration

  • New param: expand_entities (default: false) - enables entity-to-entity expansion

  • New param: entity_expansion (alias for expand_entities)

  • Existing: RECALL_EXPANSION_LIMIT=25 - total expansion results limit

[0.9.0] - 2025-11-20

🏆 Benchmark Breakthrough

  • Achieved 90.38% on LoCoMo-10 (SOTA, +2.14pp over CORE at 88.24%)

  • New benchmark report: tests/benchmarks/BENCHMARK_2025-11-20.md

🧠 Retrieval Improvements

  • Added multi-hop bridge discovery to connect disparate seed memories

  • Introduced temporal alignment scoring for time-aware recall

  • Added content token overlap to boost lexical precision

  • Hybrid scoring now combines 9 weighted components (vector, keyword, relation, content, temporal, tag, importance, confidence, recency, exact)

🔧 Configuration

  • New env vars: RECALL_BRIDGE_LIMIT, SEARCH_WEIGHT_CONTENT, SEARCH_WEIGHT_TEMPORAL

  • Tuned defaults for relation/path expansion (expand_relations, expand_paths, bridge limits)

📝 Documentation

  • Documented LoCoMo SOTA run and configuration in docs/TESTING.md

  • Updated changelog and benchmark references

[0.8.0] - 2025-11-08

🏗️ Major Refactoring
API Modularization

  • Breaking: Refactored monolithic app.py into modular API blueprints

  • New structure: automem/api/ with separate modules:

    • memory.py - Core memory CRUD operations

    • recall.py - Memory search and retrieval

    • admin.py - Administrative endpoints (reembedding, analysis)

    • health.py - Health checks and monitoring

    • enrichment.py - Enrichment pipeline management

    • consolidation.py - Memory consolidation

  • Improved code organization and maintainability

  • Reduced app.py from 1,251 lines to ~200 lines

🔒 Security Fixes
Memory ID Security

  • Critical: Removed support for client-supplied memory IDs

  • Now always generates server-side UUIDs to prevent collision/overwrite attacks

  • Eliminates potential for malicious clients to overwrite existing memories

Batch Processing Reliability

  • Fixed batch failure counter in reembedding endpoint

  • Now correctly tracks only successfully upserted items

  • Prevents incorrect success counts when Qdrant upserts fail

🚀 Railway Deployment Improvements
Template Fixes

  • Critical: Fixed secret generation syntax in railway-template.json

  • Changed from {"generator": "secret"} to ${{secret()}} (Railway's correct syntax)

  • Fixes blank FALKOR_PASSWORD, ADMIN_API_TOKEN, and AUTOMEM_API_TOKEN on deploy

  • Removed --requirepass from REDIS_ARGS to prevent Redis config parse errors

  • FalkorDB now handles authentication via FALKOR_PASSWORD env var only

Documentation Enhancements

  • Expanded docs/RAILWAY_DEPLOYMENT.md with detailed troubleshooting

  • Added step-by-step deployment instructions

  • Included cost optimization tips and backup strategies

  • Documented persistent storage configuration

  • Added environment variable reference and best practices

🧪 Testing Improvements
Live Integration Tests

  • Added safety confirmation prompt to test-live-server.sh

  • Prevents accidental test runs against production

  • New --non-interactive flag for CI/CD pipelines

  • Fixed argument parsing bug (shift mutation in for-loop)

  • test-live-server-auto.sh now wrapper for backward compatibility

LoCoMo Benchmark Support

  • Added LoCoMo benchmark integration for memory system evaluation

  • Documents AutoMem's 76.08% accuracy on LoCoMo-10 (vs CORE at 88.24%) as of November 8, 2025

  • Comprehensive benchmark results in tests/benchmarks/BENCHMARK_2025-11-08.md and summarized in docs/TESTING.md

  • Test coverage for multi-hop reasoning, temporal understanding, complex reasoning

Test Infrastructure

  • Added OpenAI chat completions mock in conftest.py

  • Improved test reliability with proper cache invalidation

  • Removed unused test dependencies (requests)

🛠️ Code Quality Improvements
Utility Consolidation

  • Removed duplicate _parse_iso_datetime from consolidation.py

  • Now imports from shared automem.utils.time module

  • Improved code reusability and consistency

Code Cleanup

  • Removed erroneous or True from hasattr checks

  • Added proper error logging for import failures

  • Removed trailing whitespace across codebase

  • Added syntax highlighting to documentation code blocks

  • Cleaned up unused dependencies in requirements-dev.txt

📝 Documentation Updates
New Documentation

  • Added docs/API.md - Comprehensive API reference

  • Added docs/TESTING.md - Testing guide with benchmark instructions

  • Enhanced README.md with clearer setup instructions

Removed Obsolete Documentation

  • Archived outdated optimization notes

  • Removed deprecated benchmark files

  • Consolidated deployment documentation

🔧 Configuration Changes
Pre-commit Hooks

  • Added .pre-commit-config.yaml for automated code quality checks

  • Includes trailing whitespace removal, end-of-file fixing

Build System

  • Updated Makefile with new testing targets

  • Improved development workflow commands

🐛 Bug Fixes

  • Fixed Qdrant delete selector to properly check for HTTP models

  • Added null-safety guard for enrichment queue in health endpoint

  • Fixed test consolidation engine cache invalidation

  • Corrected JSON syntax highlighting in documentation

[0.7.1] - 2025-10-20

🐛 Railway Deployment Fixes
Fixed - IPv6 Networking Support

  • Critical: Flask now binds to :: (IPv6 dual-stack) instead of 0.0.0.0 (IPv4 only)

  • Railway's internal networking uses IPv6 addresses (e.g., fd12:ca03:42be:...)

  • Resolves ECONNREFUSED errors when services try to connect via internal DNS

  • Memory-service now accepts connections from SSE sidecar and other services

Fixed - Port Configuration

  • Critical: Added PORT=8001 to Railway template for memory-service

  • Without explicit PORT, Flask defaults to 5000, causing connection failures

  • Template now includes PORT for all services that require it

  • Documentation emphasizes PORT is required for Railway deployments

Fixed - FalkorDB Data Persistence

  • Corrected volume mount path: /var/lib/falkordb/data (was /data)

  • FalkorDB now properly persists data across restarts

  • Updated REDIS_ARGS in template to match official FalkorDB Railway template

  • Removed health check configuration (Railway uses container monitoring for databases)

Fixed - Service Naming Consistency

  • Standardized service name to memory-service across all configs and docs

  • Updated AUTOMEM_ENDPOINT in SSE service to use correct internal DNS

  • Eliminated confusion from mixed naming (flask, automem-api, memory-service)

  • RAILWAY_PRIVATE_DOMAIN now consistently resolves to memory-service.railway.internal

📝 Documentation Improvements
Enhanced - Railway Deployment Guide

  • New troubleshooting section: "Service Connection Refused (ECONNREFUSED)"

  • Added detailed explanation of Railway's IPv6 networking

  • Documented PORT requirement and common pitfalls

  • Clarified when to use hardcoded values vs ${{...}} variable references

  • Updated FalkorDB setup instructions with correct volume paths

  • Added memory_count to health check examples for easier debugging

Enhanced - Environment Variables Reference

  • Marked PORT as required for Railway deployments

  • Added Railway networking notes explaining IPv6 dual-stack binding

  • Clarified auto-populated Railway variables and their usage

  • Updated FalkorDB connection variable documentation

Enhanced - MCP SSE Documentation

  • Added comprehensive troubleshooting steps for fetch failed errors

  • Updated service references to use memory-service consistently

  • Added note about internal DNS matching and verification commands

🔧 Improvements
Added - Debug Logging in SSE Server

  • SSE server now logs actual URLs being requested ([AutoMem] GET http://...)

  • Detailed error messages for fetch failures with endpoint information

  • Helps diagnose connection issues between services

  • Logged errors include cause and network details

Updated - Railway Template

  • All critical fixes incorporated into railway-template.json

  • Template now follows official FalkorDB patterns for environment variables

  • Removed incorrect health check configuration for FalkorDB service

  • Added PORT environment variables for all services

  • Uses FALKOR_PASSWORD consistently (matches official template)

🧹 Cleanup
Removed

  • Backup files: app.py.original, app.py.withchanges

  • Empty/unused files: claude-desktop-mcp.js

  • Test/benchmark logs: *.log, locomo_results.json

  • Empty directories: backups/

  • Unused Railway configs: railway-backup.json, railway-health-monitor.json

📁 Files Modified

  • app.py (Flask IPv6 binding)

  • mcp-sse-server/server.js (debug logging)

  • railway-template.json (PORT, volume paths, variable names)

  • docs/RAILWAY_DEPLOYMENT.md (comprehensive troubleshooting)

  • docs/ENVIRONMENT_VARIABLES.md (PORT requirements, IPv6 notes)

  • docs/MCP_SSE.md (troubleshooting guide)

🎯 Migration Notes

For existing Railway deployments:

  1. Update memory-service variables: Add PORT=8001 (required)

  2. Redeploy memory-service: Pull latest code for IPv6 binding fix

  3. Verify FalkorDB volume: Should be mounted at /var/lib/falkordb/data

  4. Check SSE endpoint: Should use http://memory-service.railway.internal:8001

  5. Test health: /health should show memory_count field

For new deployments:

  • Use the updated Railway template (all fixes included)

  • Follow updated docs/RAILWAY_DEPLOYMENT.md for manual setup

[0.7.0] - 2025-10-17

🌉 MCP over SSE Sidecar
Added - Hosted MCP Server via SSE

  • Exposes AutoMem as an MCP server over SSE for cloud clients (ChatGPT, ElevenLabs Agents)

  • Endpoints:

    • GET /mcp/sse — SSE stream (server → client); auth via Authorization: Bearer, X-API-Key, or ?api_key=

    • POST /mcp/messages?sessionId=<id> — Client → server JSON-RPC messages

    • GET /health — Sidecar health probe

  • Implementation: Node 18 + @modelcontextprotocol/sdk with JSON-RPC tool handlers mapping to AutoMem API

  • Keepalive: Heartbeats every 20s to avoid idle proxy timeouts

Security & Auth

  • Preferred auth: Authorization: Bearer <AUTOMEM_API_TOKEN>

  • Also supports: X-API-Key and ?api_key= (URL tokens may appear in logs; prefer headers)

Documentation

  • New: docs/MCP_SSE.md with deployment, auth, and troubleshooting

  • README updated to link SSE sidecar alongside the NPM MCP bridge

🚀 Deployment
Railway Template Enhancements

  • Template now provisions 3 services: automem-api, automem-mcp-sse, and FalkorDB

  • automem-mcp-sse preconfigured with AUTOMEM_ENDPOINT → http://${{automem-api.RAILWAY_PRIVATE_DOMAIN}}

  • Health checks added for the sidecar service

  • Fixed: Corrected Dockerfile path in mcp-sse-server/railway.json

  • Added: package-lock.json for reproducible SSE builds

📊 Benchmarks
Added - LoCoMo Benchmark Integration

  • End-to-end evaluation flow, docs (docs/LOCOMO_BENCHMARK.md), and test harness

  • Make targets for local and live (Railway) runs

  • Initial optimization phases (1–2.5) implemented and documented

📝 Documentation

  • INSTALLATION: One‑click Railway section updated to reflect new SSE service

  • README: Added SSE sidecar docs link under MCP and Documentation sections

📁 Files Modified

  • mcp-sse-server/: server.js, Dockerfile, package.json, package-lock.json, railway.json

  • docs/: MCP_SSE.md, LOCOMO_BENCHMARK.md

  • railway-template.json

  • INSTALLATION.md, README.md

Commits Since 0.6.0

  • Add MCP SSE sidecar and LoCoMo quick wins

  • Add MCP SSE server deployment config for Railway

  • Add multi-auth support to SSE server (Bearer, X-API-Key, query param)

  • Add package-lock.json for mcp-sse-server

  • Fix Dockerfile path in mcp-sse-server railway.json

  • Implement LoCoMo benchmark optimizations (Phases 1–2.5)

  • Add LoCoMo benchmark integration and documentation

  • Update INSTALLATION.md

[0.6.0] - 2025-10-14

🚀 Performance Optimizations
Added - Embedding Batching (40-50% Cost Reduction)

  • Feature: Batch processing for OpenAI embedding generation

  • Implementation:

    • New config: EMBEDDING_BATCH_SIZE (default: 20) and EMBEDDING_BATCH_TIMEOUT_SECONDS (default: 2.0)

    • Created _generate_real_embeddings_batch() for bulk embedding generation

    • Rewrote embedding_worker() to accumulate and batch-process memories

    • Added _process_embedding_batch() helper function

    • Extracted _store_embedding_in_qdrant() for reusability

  • Impact:

    • 40-50% reduction in API calls and overhead

    • Better throughput during high-memory periods

    • $8-15/year savings at 1000 memories/day

Added - Relationship Count Caching (80% Consolidation Speedup)

  • Feature: LRU cache for relationship counts with hourly invalidation

  • Implementation:

    • Added @lru_cache(maxsize=10000) to _get_relationship_count_cached_impl()

    • Cache key includes hour timestamp for automatic hourly refresh

    • Updated calculate_relevance_score() to use cached method

  • Impact:

    • 80% reduction in graph queries during consolidation

    • 5x faster decay consolidation runs

    • Minimal memory overhead with automatic LRU eviction

Added - Async Embedding Generation (60% Faster /memory POST)

  • Feature: Background embedding generation with queue-based processing

  • Implementation:

    • Embeddings generated asynchronously in worker thread

    • /memory POST returns immediately after FalkorDB write

    • Queue-based system prevents blocking API responses

  • Impact:

    • /memory endpoint 60% faster (was 250-400ms, now 100-150ms)

    • Better user experience for high-frequency memory storage

    • No loss in reliability - queued embeddings processed in order

Added - Enrichment Stats in /health Endpoint

  • Feature: Public enrichment metrics in health check (no auth required)

  • Implementation: Enhanced /health endpoint with enrichment section

  • Response Format:

    {
  "enrichment": {
    "status": "running",
    "queue_depth": 12,
    "pending": 15,
    "inflight": 3,
    "processed": 1234,
    "failed": 5
  }
}

  • Impact: Better monitoring and early detection of enrichment backlogs

Added - Structured Logging

  • Feature: Performance metrics in logs for analysis and debugging

  • Implementation:

    • Added structured logging to /recall endpoint with query, latency, results, filters

    • Added structured logging to /memory (store) endpoint with type, size, latency, status

    • Logs include extra={} dict with machine-parseable fields

  • Impact:

    • Easy performance analysis via log aggregation

    • Better debugging for production issues

    • Foundation for metrics dashboards

Added - Query Time Metrics

  • Feature: All API responses now include query_time_ms field

  • Implementation: Added time.perf_counter() tracking to all endpoints

  • Impact: Easy performance monitoring without parsing logs

🏗️ Code Quality & Infrastructure
Refactored - Utility Module Structure

  • Change: Extracted reusable helpers from app.py into automem/ package

  • Created Modules:

    • automem/utils/graph.py - Graph query helpers

    • automem/utils/tags.py - Tag normalization and processing

    • automem/utils/text.py - Text processing utilities

    • automem/utils/time.py - Timestamp parsing and formatting

    • automem/utils/scoring.py - Relevance scoring functions

  • Impact: Better code organization, easier testing, reduced duplication

Improved - Docker Build

  • Added: .dockerignore file for faster builds

  • Change: Updated Dockerfile to use new utility module structure

  • Impact: Smaller Docker images, faster builds

Improved - Backup Infrastructure

  • Added: GitHub Actions workflow for automated backups to S3

  • Added: Comprehensive backup documentation in docs/MONITORING_AND_BACKUPS.md

  • Added: Backup service deployment guides for Railway

  • Impact: Better disaster recovery, automated backup schedules

🐛 Bug Fixes
Fixed - Project Name Extraction

  • Issue: Feature names like "file-ops-automation" were incorrectly extracted as projects

  • Fix: Added filtering to prevent feature/module names from entity extraction

  • Impact: Cleaner entity metadata, more accurate project tracking

Fixed - /health Endpoint Attribute Error

  • Issue: /health endpoint crashed with AttributeError: 'EnrichmentStats' object has no attribute 'success_count'

  • Fix: Corrected attribute names to successes and failures (actual class fields)

  • Impact: /health endpoint now works correctly with enrichment stats

📁 Files Modified

  • app.py - Embedding batching, async generation, health endpoint, structured logging, query timing

  • consolidation.py - Relationship count caching

  • automem/utils/ - New utility module structure

  • Dockerfile - Updated for new module structure

  • .dockerignore - Created for faster builds

  • .github/workflows/backup.yml - Created automated backup workflow

  • docs/MONITORING_AND_BACKUPS.md - Updated with comprehensive backup strategies

  • OPTIMIZATIONS.md - Created comprehensive optimization documentation

  • test-optimizations.sh - Created test script for validating optimizations

📊 Performance Comparison
MetricBeforeAfterImprovement
OpenAI API calls1000/day~50-100/day40-50% ↓
Annual embedding cost$20-30$12-18$8-15 saved
/memory latency250-400ms100-150ms60% faster
Consolidation time (10k)~5 min~1 min80% faster
Production visibilityLimitedFull metrics∞ better
🎓 Based On

  • Audit by Steve (October 11, 2025)

  • Implemented highest-ROI recommendations from audit

  • Total implementation time: ~3 hours for optimizations

  • Expected ROI: 200-300% in year 1

[0.5.0] - 2025-10-13

🎯 Major Data Quality Overhaul
Fixed - Memory Type Pollution (Critical)

  • Issue: 490/773 memories (64%) had invalid types from recovery script bug

  • Root Cause: Recovery script flattened metadata.type as top-level property, overwriting actual memory type

  • Fix:

    • Added RESERVED_FIELDS filter in scripts/recover_from_qdrant.py to exclude type, confidence, content, etc.

    • Created scripts/cleanup_memory_types.py to reclassify all 490 polluted memories

    • 100% success rate - all memories reclassified to 7 valid types

  • Impact: Analytics now accurate with only valid memory types (Decision, Pattern, Preference, Style, Habit, Insight, Context)

Fixed - Tag-Based Search Not Working

  • Issue: Tag searches returned 0 results despite memories having tags

  • Root Cause: Qdrant missing keyword indexes on tags and tag_prefixes payload fields

  • Fix: Added PayloadSchemaType.KEYWORD indexes in _ensure_qdrant_collection()

  • Impact: Tag filtering now works for both exact and prefix matching

Improved - Entity Extraction Quality

Phase 1 - Error Code Filtering:

  • Added ENTITY_BLOCKLIST for HTTP errors (Bad Request, Not Found, etc.)

  • Added ENTITY_BLOCKLIST for network errors (ECONNRESET, ETIMEDOUT, etc.)

Phase 2 - Code Artifact Filtering:

  • Block markdown formatting (- **File:**, # Header, etc.)

  • Block class name suffixes (Adapter, Handler, Manager, Service, etc.)

  • Block JSON field names (starting with underscore like _embedded)

  • Block boolean literals ('false', true, null)

  • Block environment variables (all-caps with underscores)

  • Block text fragments (strings ending with colons)

Phase 3 - Project Name Extraction:

  • Issue: Project extraction regex required Project ProjectName but memories use project: project-name

  • Fix: Added pattern r"(?:in |on )?project:\s+([a-z][a-z0-9\-]+)"

  • Impact: Now correctly extracts claude-automation-hub, mcp-automem, autochat from session starts

Added - LLM-Based Memory Classification

  • Feature: Hybrid classification system (regex first, LLM fallback)

  • Implementation:

    • Enhanced MemoryClassifier with _classify_with_llm() method

    • Uses GPT-4o-mini for accurate, cost-effective classification

    • Falls back to LLM only when regex patterns don't match (~30% of cases)

  • Reclassification Completed: 413 memories reclassified with 100% success rate

  • Cost: $0.04 total for one-time reclassification, ~$0.24/year ongoing (10 memories/day)

  • Accuracy: 85-95% confidence on technical content, work logs, session starts

  • Script: Created scripts/reclassify_with_llm.py for batch reclassification

Added - Automated Backups

  • GitHub Actions: Workflow runs every 6 hours, backs up to S3

  • Railway Volumes: Built-in volume backups for redundancy

  • Dual Storage: FalkorDB (primary) + Qdrant (backup) provides data resilience

  • Documentation: Consolidated all backup docs into docs/MONITORING_AND_BACKUPS.md

Fixed - FalkorDB Data Loss Recovery

  • Issue: FalkorDB restarted and lost all memories (persistence not working)

  • Recovery: Used scripts/recover_from_qdrant.py to restore 778/780 memories from Qdrant

  • Root Cause Analysis: appendonly was set to no instead of yes

  • Prevention: Verified REDIS_ARGS in Railway and documented proper persistence configuration

📁 Files Modified

  • app.py - Enhanced entity extraction, LLM classification, Qdrant indexes

  • scripts/recover_from_qdrant.py - Fixed metadata field handling

  • scripts/cleanup_memory_types.py - Created tool for type reclassification

  • scripts/reclassify_with_llm.py - Created LLM-based reclassification tool

  • docs/MONITORING_AND_BACKUPS.md - Updated with comprehensive backup strategies

  • docs/RAILWAY_DEPLOYMENT.md - Updated references to backup documentation

  • README.md - Updated architecture and documentation links

  • .github/workflows/backup.yml - Created automated backup workflow

📊 Impact Summary

  • Memory Types: 79 invalid types → 7 valid types (100% cleanup)

  • Reclassified: 903 total memories

    • 490 via cleanup script (invalid types → valid types)

    • 413 via LLM (fallback "Memory" → specific types)

    • 100% success rate on both

  • Final Distribution: Context (47%), Decision (16%), Insight (13%), Habit (12%), Preference (9%), Pattern (3%), Style (<1%)

  • Entity Quality: Clean extraction, no error codes or code artifacts

  • Tag Search: Fully functional with proper indexing

  • Backups: Automated every 6 hours to S3

  • Data Recovery: 99.7% recovery rate (778/780) from Qdrant

  • Classification: Hybrid system with 85-95% LLM confidence

🚀 Deployment

All changes deployed to Railway at automem.up.railway.app

💰 Cost Analysis

  • LLM Classification: $0.04 one-time + $0.24/year ongoing (~$0.02/month)

  • S3 Backups: Minimal (~$0.05/month for storage + lifecycle rules)

  • Qdrant: Existing free tier (1GB)

  • Railway: Existing deployment ($5/month hobby plan)

[Prior Releases]

See git history for previous changes.

273 files · 249 not served here

Advantages

  • Avoids redundant LLM calls during recall by using direct graph and vector index lookups. evidence: README.md
  • Records typed relationships between memories to surface the 'why' behind decisions rather than just isolated facts. evidence: README.md
  • Provides a unified memory store accessible across multiple different AI tools and chat applications. evidence: README.md

Limitations

  • Tags act as a hard filter, meaning memories without the queried tag are excluded even if they are semantically relevant. evidence: README.md
  • The system does not yet reliably resolve conflicting facts or prioritize the newest version of information automatically. evidence: README.md
  • The MCP SSE bridge currently lacks support for passing through state_mode configurations. evidence: README.md

Security

Risk level: Medium risk

This brain runs

Git hooks (8)

  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/psf/black at 24.4.2 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/pycqa/isort at 5.13.2 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/pycqa/flake8 at 7.1.1 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/compilerla/conventional-pre-commit at v3.2.0 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/pre-commit/pre-commit-hooks at v4.6.0 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/Yelp/detect-secrets at v1.5.0 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: bash -c 'PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./venv/bin/pytest tests/ --ignore=tests/benchmarks --ignore=tests/test_integration.py -x -q'
  • .pre-commit-config.yaml: bash -c 'command -v coderabbit >/dev/null 2>&1 || { echo "coderabbit CLI not installed, skipping"; exit 0; }; coderabbit review --type committed --plain'

Agent instructions that run or fetch something (39)

  • AGENTS.md: `make install`: Create `.venv` (and symlink `venv -> .venv`) and install dev deps.
  • AGENTS.md: `make dev`: Start local stack via Docker (FalkorDB, Qdrant, API).
  • AGENTS.md: `make test`: Run unit tests (fast, no services).
  • AGENTS.md: `make test-integration`: Start Docker and run full integration tests.
  • AGENTS.md: `make fmt` / `make lint`: Format with Black/Isort and lint with Flake8.
  • AGENTS.md: `make bench-eval BENCH=locomo-mini`: Run snapshot-based benchmark (~2 min).
  • AGENTS.md: `make deploy` / `make status`: Deploy/check Railway.
  • AGENTS.md: Quick health: `curl :8001/health`. · uses the network
  • AGENTS.md: Run `pre-commit install` and `make fmt && make lint` before committing.
  • AGENTS.md: Unit tests: `make test`.
  • AGENTS.md: Integration: `make test-integration` (requires Docker).
  • AGENTS.md: | Tier | Benchmark | Command | Runtime | Cost | When to use | |------|-----------|---------|---------|------|-------------| | 0 | Unit tests | `make test` | 30s | free | Every change | | 1 | LoCoMo-mini (2 convos, 304 Qs) | `make bench-eval BENCH=locomo-mini` | 2-3 min | free / ~$0.20 …[+355 chars]
  • AGENTS.md: `make bench-eval BENCH=locomo-mini CONFIG=baseline` — eval from snapshot (~2 min).
  • AGENTS.md: `make bench-compare BENCH=locomo CONFIG=<name> BASELINE=baseline` — A/B compare two configs.
  • AGENTS.md: `make bench-compare-branch BRANCH=<branch>` — compare a branch against baseline.
  • AGENTS.md: `make bench-ingest BENCH=locomo` — ingest + snapshot (run once per embedding change).
  • AGENTS.md: `make bench-health` — recall health check (score distribution, entity quality, latency).
  • AGENTS.md: Run `make bench-eval BENCH=locomo-mini` on `main` to confirm the current baseline.
  • AGENTS.md: Run the same eval on the branch.
  • AGENTS.md: Promote to `make bench-eval BENCH=locomo` (full) before merge.
  • AGENTS.md: `benchmarks/snapshots/` — Qdrant/FalkorDB snapshot data (gitignored, regenerate with `make bench-ingest`).
  • AGENTS.md: `benchmarks/results/` — per-run result JSONs (gitignored).
  • AGENTS.md: release-please and GHCR `:stable` then run on `main`.
  • CLAUDE.md: `GET /consolidate/status` - Check consolidation scheduler status and last run times
  • CLAUDE.md: Adds short summaries, timestamps (`enriched_at`), and per-run metrics under `metadata.enrichment`.
  • CLAUDE.md: # Run tests
  • CLAUDE.md: make test-integration # Starts services and runs integration tests
  • CLAUDE.md: make test-live # Same as above via Makefile
  • CLAUDE.md: JIT_ENRICHMENT_ENABLED=true # Run entity/summary extraction inline on recall for unenriched memories
  • CLAUDE.md: Install spaCy locally to improve entity extraction:
  • CLAUDE.md: pip install spacy
  • CLAUDE.md: python -m spacy download en_core_web_sm
  • CLAUDE.md: **Local Development** - Make changes and test with `make dev`
  • CLAUDE.md: **Unit Tests** - Verify with `make test`
  • CLAUDE.md: **Integration Tests** - Validate with `make test-integration`
  • CLAUDE.md: **Deploy to Railway** - Push changes with `make deploy`
  • CLAUDE.md: **Live Validation** - Test deployed instance with `make test-live`
  • CLAUDE.md: **Benchmarking** - Validate performance with `make test-locomo-live`
  • CLAUDE.md: # Run integration tests against Railway

Install scripts (1)

  • Makefile (make install): echo "🔧 Setting up development environment..."; bash scripts/bootstrap_dev.sh; echo "✅ Virtual environment ready!"; echo "💡 Run 'source .venv/bin/activate' to activate"
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:9)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:16)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:23)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:30)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:38)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:50)
  • Medium risk: runs-instruction-instruction-network (AGENTS.md:23)
  • Low risk: network-instructions (.pre-commit-config.yaml:2)
  • Low risk: network-instructions (CLAUDE.md:299)
  • Low risk: network-instructions (Makefile:91)
  • Low risk: scripts-present (scripts/bootstrap_dev.sh)

Attribution and licence

First committed by
GitHub avatar of jack-arturojack-arturo
Publisher
Very Good Plugins (Community)
Source
verygoodplugins/automem · commit 1a7ba1a
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jack-arturo, mikemikimike, zackkatz, dexhunter

AutoGineer is not affiliated with or endorsed by jack-arturo or Very Good Plugins.

Install from source

249 of its files are not served here, so there is no ZIP. verygoodplugins/automem at 1a7ba1a