Agent Memory

A standalone memory platform for AI coding agents with a hub server, OpenCode adapter plugin, and CLI for sysadmin workflows.

Visual Overview

Project Memory Timeline:

User Profile Viewer:

Core Features

Local vector database with SQLite + HNSW (hnswlib-wasm), persistent project memories, automatic user profile learning, unified memory-prompt timeline, full-featured web UI, intelligent prompt-based memory extraction, multi-provider AI support (OpenAI, Anthropic), 12+ local embedding models, smart deduplication, and built-in privacy protection.

Prerequisites

This plugin uses hnswlib-node for fast vector similarity search, which requires native compilation. Ensure you have:

All platforms:

• Python 3.x
• A C++ compiler (gcc, clang, or MSVC)
• make or CMake

Platform-specific setup:

| Platform | Requirements | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | macOS | Xcode Command Line Tools: xcode-select --install | | Linux | Build essentials: sudo apt install build-essential python3 (Debian/Ubuntu) or sudo pacman -S base-devel python (Arch) | | Windows | Visual Studio Build Tools with C++ workload, or Windows Build Tools: npm install -g windows-build-tools |

Getting Started

OpenCode Adapter (Plugin)

Add to your OpenCode configuration at ~/.config/opencode/opencode.json:

{
  "plugin": ["@arwiesner/agent-mem"],
}

The plugin downloads automatically on next startup.

For legacy installs, @arwiesner/opencode-mem and ~/.config/opencode/opencode-mem.jsonc remain supported.

Usage Examples (OpenCode tool)

memory({ mode: "add", content: "Project uses microservices architecture" });
memory({ mode: "search", query: "architecture decisions" });
memory({ mode: "profile" });
memory({ mode: "list", limit: 10 });

Access the web interface at http://127.0.0.1:4747 for visual memory browsing and management.

Standalone CLI

The CLI supports local or remote (hub) operation:

# Local (uses local config + storage)
agent-mem status
agent-mem list --limit 5
agent-mem search "vector search"
agent-mem add "Store architecture notes" --tags "architecture,search"
agent-mem forget mem_123
agent-mem profile

# Remote (hub)
agent-mem status --server http://127.0.0.1:4747 --token <token>
agent-mem search "sqlite" --server http://127.0.0.1:4747 --token <token>

Hub Server

Run the hub with the existing server entrypoint:

bun run build
bun run server

Configuration Essentials

Configure at ~/.config/agent-mem/agent-mem.jsonc (legacy ~/.config/opencode/opencode-mem.jsonc still supported):

{
  "storagePath": "~/.agent-mem/data",
  "userEmailOverride": "[email protected]",
  "userNameOverride": "John Doe",
  "embeddingModel": "Xenova/nomic-embed-text-v1",
  "webServerEnabled": true,
  "webServerPort": 4747,

  "autoCaptureEnabled": true,
  "autoCaptureLanguage": "auto",
  "memoryProvider": "openai-chat",
  "memoryModel": "gpt-4o-mini",
  "memoryApiUrl": "https://api.openai.com/v1",
  "memoryApiKey": "sk-...",
  "memoryTemperature": 0.3,

  "showAutoCaptureToasts": true,
  "showUserProfileToasts": true,
  "showErrorToasts": true,

  "syncEnabled": false,
  "syncMode": "server",
  "syncServerUrl": "http://127.0.0.1:4747",
  "syncToken": "",
  "syncIntervalMs": 60000,
  "syncBatchSize": 500,
  "syncSkewMs": 10000,

  "userProfileAnalysisInterval": 10,
  "maxMemories": 10,

  "compaction": {
    "enabled": true,
    "memoryLimit": 10,
  },
  "chatMessage": {
    "enabled": true,
    "maxMemories": 3,
    "excludeCurrentSession": true,
    "maxAgeDays": undefined,
    "injectOn": "first",
  },
}

API Key Formats:

"memoryApiKey": "sk-..."
"memoryApiKey": "file://~/.config/agent-mem/api-key.txt"
"memoryApiKey": "env://OPENAI_API_KEY"

Full documentation available in this README.

Hub Sync (Docker)

Run the hub server in Docker using docker-compose.yml:

services:
  agent-mem-hub:
    build: .
    ports:
      - "4747:4747"
    volumes:
      - ~/.agent-mem:/data
      - ~/.config/agent-mem/agent-mem.jsonc:/home/bun/.config/agent-mem/agent-mem.jsonc:ro
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:4747/api/sync/status"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Set these values in ~/.config/agent-mem/agent-mem.jsonc for the hub:

{
  "storagePath": "/data",
  "webServerHost": "0.0.0.0",
  "webServerPort": 4747,
  "syncEnabled": true,
  "syncMode": "server",
  "syncToken": "<shared-token>",
}

Clients should use:

{
  "syncEnabled": true,
  "syncMode": "client",
  "syncServerUrl": "http://<hub-ip>:4747",
  "syncToken": "<shared-token>",
}

Security note: token auth is required. If exposing beyond LAN, put the hub behind a reverse proxy with TLS.

Sync troubleshooting

Common checks:

• 401 Unauthorized: confirm syncToken matches on hub + client and is resolved correctly.
• No changes syncing: confirm syncEnabled: true, syncMode matches hub/client roles, and the client can reach syncServerUrl.
• Clock skew: if clients are far off in time, increase syncSkewMs temporarily.
• Docker health: docker compose ps should show the hub as healthy; the healthcheck calls /api/sync/status.

Token guidance:

• Generate a long random token (e.g., openssl rand -hex 32).
• Store it using env:// or file:// to avoid committing secrets.

Development & Contribution

Build and test locally:

bun install
bun run build
bun run typecheck
bun run format

This project is actively seeking contributions to become the definitive memory plugin for AI coding agents. Whether you are fixing bugs, adding features, improving documentation, or expanding embedding model support, your contributions are critical. The codebase is well-structured and ready for enhancement. If you hit a blocker or have improvement ideas, submit a pull request - we review and merge contributions quickly.

License & Links

MIT License - see LICENSE file

• Repository: https://github.com/Alex-Wiesner/agent-mem
• Issues: https://github.com/Alex-Wiesner/agent-mem/issues
• OpenCode Platform: https://opencode.ai

Inspired by opencode-supermemory