Project Structure

AutoMem Server (`verygoodplugins/automem`)

The AutoMem server repository follows a hybrid Python/Node.js structure with three primary deployment targets: the core Flask API service, the MCP bridge server, and operational scripts.

Directory Layout

graph TB
    Root["automem/\nRepository Root"]

    subgraph "Python Source"
        AppPy["app.py\nThin Flask bootstrap"]
        ConsolPy["consolidation.py\nBackground workers"]

        Root --> AppPy
        Root --> ConsolPy
    end

    subgraph "Node.js Integration"
        MCPDir["mcp-sse-server/\nMCP bridge service"]
        MCPNode["node_modules/\n(ignored)"]

        Root --> MCPDir
        MCPDir --> MCPNode
    end

    subgraph "Scripts & Tools"
        ScriptsDir["scripts/\nOperational scripts"]
        BackupScript["backup_automem.py"]
        RecoverScript["recover_from_qdrant.py"]
        MonitorScript["health_monitor.py"]

        Root --> ScriptsDir
        ScriptsDir --> BackupScript
        ScriptsDir --> RecoverScript
        ScriptsDir --> MonitorScript
    end

    subgraph "Configuration"
        Env[".env\n(ignored, contains secrets)"]
        Requirements["requirements.txt\nrequirements-dev.txt"]
        Dockerfile["Dockerfile"]
        RailwayToml["railway.toml"]

        Root --> Requirements
        Root --> Dockerfile
        Root --> RailwayToml
    end

Core Service Modules

`app.py` — Thin Flask Bootstrap

A small entry module that creates the Flask app, registers @app.before_request auth, and delegates startup to automem/runtime_wiring.py. All business logic, routes, workers, and configuration live in the automem/ package — not in app.py.

Responsibility	Implementation
Service startup and wiring	Imports from `automem/runtime_wiring.py`
Flask app factory	Delegates to `automem/api/` route modules
Background worker launch	Delegates to worker modules in `automem/`
Configuration loading	`automem/config.py`

`automem/` — Core Python Package

The main package containing all business logic, organized by domain:

automem/
├── __init__.py
├── config.py                   # All configuration constants
├── service_state.py            # ServiceState dataclass
├── service_runtime.py          # Runtime initialization helpers
├── service_runtime_bindings.py
├── runtime_wiring.py           # Server startup orchestration
├── runtime_environment.py
├── app_helper_bindings.py
├── api/
│   ├── memory.py               # POST/GET/PATCH/DELETE /memory routes
│   ├── recall.py               # GET /recall routes
│   ├── graph.py                # Graph query routes
│   ├── admin.py                # Admin operations
│   ├── health.py               # Health endpoint
│   ├── enrichment.py           # Enrichment status/reprocess
│   ├── consolidation.py        # Consolidation trigger/status
│   ├── viewer.py               # Graph viewer routes
│   ├── stream.py               # SSE streaming
│   ├── auth_helpers.py         # Authentication middleware
│   ├── runtime_bootstrap.py
│   ├── runtime_memory_routes.py
│   └── runtime_recall_routes.py
├── classification/
│   ├── __init__.py
│   └── memory_classifier.py
├── consolidation/
│   ├── runtime_bindings.py
│   ├── runtime_helpers.py
│   ├── runtime_routes.py
│   └── runtime_scheduler.py
├── embedding/
│   ├── provider.py             # Base provider class
│   ├── provider_init.py        # Auto-selection logic
│   ├── openai.py
│   ├── voyage.py
│   ├── fastembed.py
│   ├── ollama.py
│   ├── placeholder.py
│   ├── runtime_pipeline.py
│   ├── runtime_bindings.py
│   └── runtime_helpers.py
├── enrichment/
│   ├── runtime_bindings.py
│   ├── runtime_helpers.py
│   ├── runtime_orchestration.py
│   ├── runtime_queue_bindings.py
│   └── runtime_worker.py
├── search/
│   ├── runtime_recall_helpers.py
│   ├── runtime_relations.py
│   └── runtime_keywords.py
├── stores/
│   ├── graph_store.py
│   ├── vector_store.py
│   └── runtime_clients.py
├── sync/
│   ├── runtime_bindings.py
│   └── runtime_worker.py
├── analytics/
│   └── runtime_helpers.py
└── utils/
    ├── entity_extraction.py
    ├── scoring.py
    ├── tags.py
    ├── time.py
    ├── text.py
    ├── graph.py
    └── validation.py

`consolidation.py` — Dream-Inspired Maintenance

Self-contained consolidation engine with no Flask dependencies. Designed for both scheduled background execution and manual CLI invocation.

Class	Purpose	Key Methods
`MemoryConsolidator`	Execute consolidation tasks	`consolidate()`, `calculate_relevance_score()`, `discover_creative_associations()`, `cluster_similar_memories()`, `apply_controlled_forgetting()`
`ConsolidationScheduler`	Manage task intervals	`run_scheduled_tasks()`, `should_run()`, `get_next_runs()`
`GraphLike` (Protocol)	Database abstraction	`query()` method only
`VectorStoreProtocol` (Protocol)	Vector store abstraction	`delete()` method only

Caching optimization: Relationship count queries use @lru_cache with hourly invalidation (consolidation.py:201-216).

`mcp-sse-server/` — Node.js SSE Bridge

Translates Model Context Protocol (MCP) tool calls into AutoMem REST API requests. Enables ChatGPT, ElevenLabs, and other SSE-compatible AI platforms to access AutoMem.

Port: 8080 (configurable via PORT environment variable)
Connects to Flask API at AUTOMEM_URL (default: http://localhost:8001)
Key files: server.js (SSE endpoint handlers, JSON-RPC to REST translation), package.json

Operational Scripts

Production-ready Python scripts for data protection and disaster recovery.

Script	Purpose	Dependencies
`backup_automem.py`	Export FalkorDB + Qdrant to S3/local	`boto3`, `falkordb`, `qdrant-client`
`recover_from_qdrant.py`	Rebuild FalkorDB graph from Qdrant payloads	`falkordb`, `qdrant-client`
`restore_from_backup.py`	Restore from compressed JSON backups	`falkordb`, `qdrant-client`
`health_monitor.py`	Detect count drift between databases	`requests`, optional webhook client

All scripts connect directly to FalkorDB and Qdrant, bypassing the Flask API. They read the same environment variables as app.py. The backup_automem.py script runs every 6 hours via a GitHub Actions workflow.

Configuration Management

Environment Variable Load Order (`automem/config.py`)

automem/config.py calls load_dotenv twice and never sets override=True, so a value that is already set is never replaced. In order of precedence, highest first:

Variables already in the process environment, for example secrets that Railway injects
The project .env, loaded first by load_dotenv() with no path (in a normal, non-interactive run python-dotenv searches upward from the automem/ package directory)
~/.config/automem/.env, loaded second; it only fills in variables that are still unset

Key Configuration Categories

Category	Example Variables	Defined In
Database Connections	`FALKORDB_HOST`, `QDRANT_URL`	`automem/config.py`
Authentication	`AUTOMEM_API_TOKEN`, `ADMIN_API_TOKEN`	`automem/config.py`
Consolidation Intervals	`CONSOLIDATION_DECAY_INTERVAL_SECONDS`	`automem/config.py`
Enrichment Tuning	`ENRICHMENT_MAX_ATTEMPTS`, `ENRICHMENT_SIMILARITY_THRESHOLD`	`automem/config.py`
Embedding Batching	`EMBEDDING_BATCH_SIZE`, `EMBEDDING_BATCH_TIMEOUT_SECONDS`	`automem/config.py`
Search Weights	`SEARCH_WEIGHT_VECTOR`, `SEARCH_WEIGHT_KEYWORD`	`automem/config.py`

Containerization Files

File	Purpose	Key Settings
`Dockerfile`	Container image definition	Python 3.11, installs spaCy model
`docker-compose.yml`	Local development stack	Orchestrates Flask + FalkorDB + Qdrant
`railway.json`	Railway deployment config	Service definitions, port mappings

Docker Compose services:

flask-api: Flask API (port 8001)
falkordb: Graph database (port 6379)
qdrant: Vector database (port 6333)

Testing Infrastructure

`tests/` — Pytest Test Suites

The test suite covers consolidation, API endpoints, enrichment, embedding providers, and integration flows:

tests/
├── conftest.py
├── test_consolidation_engine.py
├── test_api_endpoints.py
├── test_app.py
├── test_enrichment.py
├── test_embedding_providers.py
├── test_integration.py
├── test_content_size.py
├── test_vector_size_safety.py
├── test_recall_entity_extraction.py
├── support/
├── contracts/
└── benchmarks/

Tests use pytest markers to separate execution tiers: unit (no external services, runs with make test, which then runs the MCP bridge’s Node tests through make test-node), integration (requires Docker stack, runs with make test-integration), and live (runs against a deployed Railway instance).

Mock objects (defined in tests/test_consolidation_engine.py and tests/support/):

FakeGraph: Implements GraphLike protocol with in-memory state — imported from tests/support/fake_graph.py
FakeVectorStore: Implements VectorStoreProtocol for deletion tracking — defined in tests/test_consolidation_engine.py:19-24

Test philosophy: Consolidation tests use deterministic mocks and frozen time to ensure reproducible relevance score calculations.

File Naming Conventions

Pattern	Purpose	Examples
`*.py`	Python modules	`app.py`, `consolidation.py`
`test_*.py`	Pytest test files	`test_consolidation_engine.py`
`*_automem.py`	Operational scripts	`backup_automem.py`, `restore_from_backup.py`
`*.md`	Markdown documentation	`README.md`, `OPTIMIZATIONS.md`
`*.sh`	Shell scripts	`test-optimizations.sh`
`.env`	Environment configuration	`.env`, `~/.config/automem/.env`
`*.yml`	YAML configuration	`docker-compose.yml`

Gitignored patterns: __pycache__/, venv/, .venv/, backups/, node_modules/, .env

Deployment Artifact Boundaries

Different deployment scenarios use different subsets of the repository:

Railway (Production): Single container running app.py (which imports the automem/ package), consolidation runs in background thread
Docker Compose (Local): Multi-container with separate database services
Bare Metal (Development): Python process + external databases
MCP Bridge: Optional Node.js service for AI platform integration
Scripts: Standalone utilities connecting directly to databases

MCP Client (`verygoodplugins/mcp-automem`)

The mcp-automem package uses a TypeScript project structure with distinct directories for source code, templates, build artifacts, and configuration files.

Directory Layout

This is a selected layout, not an exhaustive listing. src/ and src/cli/ contain further helper modules, and templates/ also holds shared root-level files.

graph TB
    ROOT["."]

    ROOT --> SRC["src/"]
    ROOT --> TEMPLATES["templates/"]
    ROOT --> PLUGINS["plugins/"]
    ROOT --> DIST["dist/"]
    ROOT --> GITHUB[".github/"]
    ROOT --> HUSKY[".husky/"]

    SRC --> INDEX["index.ts\n(MCP server entry point)"]
    SRC --> CLIENT["automem-client.ts\n(HTTP client)"]
    SRC --> TYPES["types.ts\n(TypeScript interfaces)"]
    SRC --> CLI["cli/"]

    CLI --> SETUP["setup.ts"]
    CLI --> INSTALL["install.ts"]
    CLI --> CLIENTS["clients.ts"]
    CLI --> CLAUDECODE["claude-code.ts"]
    CLI --> CURSOR["cursor.ts"]
    CLI --> CODEX["codex.ts"]
    CLI --> COPILOT["copilot.ts"]
    CLI --> HERMES["hermes.ts"]
    CLI --> GROK["grok.ts"]
    CLI --> OPENCLAW["openclaw.ts"]
    CLI --> QUEUE["queue.ts"]
    CLI --> MIGRATE["migrate.ts"]
    CLI --> UNINSTALL["uninstall.ts"]
    CLI --> CLOUD["cloud/"]

    TEMPLATES --> TCCLI["claude-code/\nhooks, settings"]
    TEMPLATES --> TCUR["cursor/\n.mdc rule template, user rules"]
    TEMPLATES --> TCODEX["codex/\nconfig.toml, memory-rules.md"]
    TEMPLATES --> TCOPILOT["copilot/\ninstructions, hooks, profiles, scripts"]
    TEMPLATES --> THERMES["hermes/\nmemory-rules.md, provider/"]
    TEMPLATES --> TGROK["grok/\nconfig.toml, memory-rules.md"]
    TEMPLATES --> TOCLAW["openclaw/\nSKILL.md variants, setup guide"]
    TEMPLATES --> TANTI["antigravity/\nmcp_config.json"]

    PLUGINS --> PAUTOMEM["automem/"]
    PAUTOMEM --> PCCLI[".claude-plugin/\nplugin.json"]
    PAUTOMEM --> PCOMMANDS["commands/"]
    PAUTOMEM --> PHOOKS["hooks/"]
    PAUTOMEM --> PSCRIPTS["scripts/"]
    PAUTOMEM --> PSKILLS["skills/\nmemory-management/"]
    ROOT --> ROOTPLUGIN[".claude-plugin/\nmarketplace.json"]

    GITHUB --> WORKFLOWS["workflows/\nCI/CD YAML files"]

    DIST --> DISTJS["*.js\n(Compiled code)"]
    DIST --> DISTDTS["*.d.ts\n(Type definitions)"]
    DIST --> DISTMAP["*.js.map\n(Source maps)"]

Source Directory (`src/`)

Entry Point: `index.ts`

The src/index.ts file serves dual purposes based on command-line arguments:

Server Mode (no arguments): Launches an MCP server using StdioServerTransport from @modelcontextprotocol/sdk
CLI Mode (with arguments): Routes commands to appropriate CLI handlers in src/cli/

HTTP Client: `automem-client.ts`

The src/automem-client.ts file implements the AutoMemClient class, providing a typed HTTP interface to the AutoMem backend service.

Method	HTTP Endpoint	Purpose
`storeMemory()`	`POST /memory`	Store new memory with content, tags, metadata
`recallMemory()`	`GET /recall`, or `GET /memory/by-tag` internally when called with `tags` + `exhaustive: true`	Hybrid search (vector + keyword + tags), or tag-only filtering
`associateMemories()`	`POST /associate`	Create typed relationships
`updateMemory()`	`PATCH /memory/:id`	Update existing memory fields
`deleteMemory()`	`DELETE /memory/:id`	Remove memory and embedding
`checkHealth()`	`GET /health`	Database connectivity status

Configuration resolution (priority order):

Constructor parameters (if provided)
Environment variables (AUTOMEM_API_URL, AUTOMEM_API_KEY) — AUTOMEM_ENDPOINT is accepted as a deprecated alias for AUTOMEM_API_URL
.env file (loaded via dotenv)

Type Definitions: `types.ts`

The src/types.ts file defines the client’s shared TypeScript types:

Configuration types: AutoMemConfig
Memory operation arguments: StoreMemoryArgs, RecallMemoryArgs, AssociateMemoryArgs, UpdateMemoryArgs, DeleteMemoryArgs
API response types: RecallResult, StoreMemoryResult, AssociateMemoryResult, DeleteMemoryResult, HealthStatus
Value types: MemoryType, RelationType

CLI Commands (`src/cli/`)

Each CLI command is implemented as a separate module with a main run*() function. CLI handlers follow a consistent pattern: --dry-run flag for safe preview, template rendering from templates/ directory, filesystem operations with error handling, and user-friendly output with next-step instructions.

Templates Directory (`templates/`)

The templates/ directory contains platform-specific integration files that are copied to user systems during installation. These files are included in the published npm package.

Selected layout of templates/ (not exhaustive: the root-level Markdown files are omitted, and the contents of the copilot/ subdirectories and hermes/provider/ are summarized):

templates/
├── antigravity/
│   └── mcp_config.json
├── claude-code/
│   ├── hooks/               # Shell scripts triggered by Claude events
│   │   ├── automem-session-start.sh   # SessionStart recall
│   │   ├── automem-track-store.sh     # PostToolUse store tracking
│   │   └── automem-stop-nudge.sh      # Optional Stop nudge (--profile nudged)
│   ├── settings.json        # Base hook configuration (default silent profile)
│   └── settings.stop-nudge.json  # Adds Stop nudge hook registration
├── codex/
│   ├── config.toml
│   └── memory-rules.md
├── copilot/
│   ├── automem.instructions.md
│   ├── hooks/               # JSON hook definitions
│   ├── profiles/            # full.json, lean.json
│   └── scripts/             # .sh and .ps1 hook scripts
├── cursor/
│   ├── automem.mdc.template # Cursor rule template
│   ├── rule-evals.md
│   └── user-rules.md
├── grok/
│   ├── config.toml
│   └── memory-rules.md
├── hermes/
│   ├── memory-rules.md
│   └── provider/            # Python provider files and plugin.yaml
├── openclaw/
│   ├── OPENCLAW_SETUP.md
│   ├── skill/               # SKILL.md
│   ├── skill-legacy/        # SKILL.md
│   └── skill-mcp/           # SKILL.md
├── claude_desktop_config.json
└── cursor_mcp.json

Template file types:

Type	Extension	Purpose	Target Platform
Hook Scripts	`.sh`, `.ps1`	Event-driven automation	Claude Code (`.sh`), Copilot (`.sh`, `.ps1`)
Rule Files	`.md`, `.mdc.template`	AI assistant instructions	Claude Code, Claude Desktop, Cursor, Codex, Copilot, Grok, Hermes, OpenClaw
Config Snippets	`.json`, `.toml`	MCP server configuration	Claude Desktop, Cursor, Antigravity, Codex, Grok
Settings	`.json`	Hook permissions & matchers	Claude Code

Build Artifacts (`dist/`)

The dist/ directory is generated by TypeScript compilation (tsc) and contains:

JavaScript files (.js) — Compiled from TypeScript source
Type declarations (.d.ts) — For TypeScript consumers
Source maps (.js.map) — For debugging compiled code

TypeScript configuration (tsconfig.json):

outDir: "dist" — Output location
declaration: true — Generate .d.ts files
sourceMap: true — Generate source maps
module: "NodeNext" — Node.js module format; package.json sets "type": "module", so the output is ES modules
target: "ES2022" — JavaScript target version

Build scripts:

Script	Command	Purpose
`prebuild`	`node scripts/sync-template-versions.mjs`	Sync template versions before compile
`build`	`tsc`	Compile TypeScript source
`postbuild`	`node scripts/build-openclaw-plugin-package.mjs && chmod +x dist/index.js`	Package OpenClaw plugin + make executable
`dev`	`tsx watch src/index.ts`	Hot-reload development
`typecheck`	`tsc --noEmit`	Validate types without building

Plugins Directory (`plugins/`)

plugins/automem/ packages AutoMem as an installable Claude Code plugin: .claude-plugin/plugin.json (plugin manifest), plus commands/, hooks/, scripts/, and skills/memory-management/. A separate top-level .claude-plugin/marketplace.json registers the plugin in the Claude Code plugin marketplace. There is no server/ subdirectory — this is a Claude Code plugin bundle, not a packaged MCP server.

Configuration Files

Root-Level Configuration

The repository root contains multiple configuration files:

File	Purpose
`package.json`	npm scripts, dependencies, package metadata
`tsconfig.json`	TypeScript compiler options
`eslint.config.mjs`	ESLint flat config (ESLint 9+)
`.commitlintrc.cjs`	Conventional commit message validation
`.prettierrc`	Code formatting rules
`release-please-config.json`	Automated release configuration
`.release-please-manifest.json`	Current version tracking
`env.example`	Template for required environment variables

Version Synchronization

Five files must maintain version consistency (managed by release-please):

package.json — e.g. "version": "0.16.0" (at mcp-automem 0.16.0)
server.json (repo root) — same version string
manifest.json — same version string
plugins/automem/.claude-plugin/plugin.json — same version string
.claude-plugin/marketplace.json — same version string

The release-please.yml workflow automatically updates all five files when creating releases based on conventional commits.

GitHub Workflows (`.github/`)

Workflow	Trigger	Purpose
`ci.yml`	PR, push to main	Lint, build, test, coverage
`security.yml`	PR, push, schedule	CodeQL, npm audit
`release-please.yml`	Push to main	Version bump, changelog, publish
`semantic-pr-title.yml`	PR open/edit	Validate PR title format

Git Hooks (`.husky/`)

The .husky/commit-msg hook runs commitlint to validate commit messages against Conventional Commits format before allowing the commit.

Accepted types: fix, feat, chore, docs, refactor, test, ci, build, perf, revert

Published Package Contents

The files array in package.json specifies what gets included in the npm package:

What’s included: dist/, templates/, plugins/, env.example, README.md, CHANGELOG.md

What’s excluded: Source code (src/), tests, development configs, CI/CD files, .tsbuildinfo

File Locations by Use Case

Task	Files to Modify
Add a new MCP tool	`src/index.ts` (schema + handler), `src/automem-client.ts` (client method), `src/types.ts`
Add a new CLI command	Create `src/cli/new-command.ts`, import and route in `src/index.ts`
Modify platform integration	Edit `templates/<platform>/`, update `src/cli/<platform>.ts`, sync to `plugins/`
Change build output	Modify `tsconfig.json`, update `package.json` `main` and `types` fields
Add release automation	Edit `.github/workflows/release-please.yml`, update `.release-please-manifest.json`

Project Structure

AutoMem Server (verygoodplugins/automem)

Directory Layout

Core Service Modules

app.py — Thin Flask Bootstrap

automem/ — Core Python Package

consolidation.py — Dream-Inspired Maintenance

mcp-sse-server/ — Node.js SSE Bridge

Operational Scripts

Configuration Management

Environment Variable Load Order (automem/config.py)

Key Configuration Categories

Containerization Files

Testing Infrastructure

tests/ — Pytest Test Suites

File Naming Conventions

Deployment Artifact Boundaries

MCP Client (verygoodplugins/mcp-automem)

Directory Layout

Source Directory (src/)

Entry Point: index.ts

HTTP Client: automem-client.ts

Type Definitions: types.ts

CLI Commands (src/cli/)

Templates Directory (templates/)

Build Artifacts (dist/)

Plugins Directory (plugins/)

Configuration Files

Root-Level Configuration

Version Synchronization

GitHub Workflows (.github/)

Git Hooks (.husky/)

Published Package Contents

File Locations by Use Case

AutoMem Server (`verygoodplugins/automem`)

`app.py` — Thin Flask Bootstrap

`automem/` — Core Python Package

`consolidation.py` — Dream-Inspired Maintenance

`mcp-sse-server/` — Node.js SSE Bridge

Environment Variable Load Order (`automem/config.py`)

`tests/` — Pytest Test Suites

MCP Client (`verygoodplugins/mcp-automem`)

Source Directory (`src/`)

Entry Point: `index.ts`

HTTP Client: `automem-client.ts`

Type Definitions: `types.ts`

CLI Commands (`src/cli/`)

Templates Directory (`templates/`)

Build Artifacts (`dist/`)

Plugins Directory (`plugins/`)

GitHub Workflows (`.github/`)

Git Hooks (`.husky/`)