Agents Memory Sidecar

Local-first shared memory for MCP-capable AI agents.

Agents Memory Sidecar lets tools such as Codex, Claude Code, Grok, agy, Pi, and other MCP clients share operational memory through one local sidecar. It is designed for coding agents that need to search prior context before changing a project and store durable non-secret facts after work is validated.

Agent CLI -> stdio MCP wrapper -> localhost HTTP sidecar -> PostgreSQL + pgvector

The HTTP server is intended to listen on 127.0.0.1 only. Do not expose it directly to the public internet.

Features

• MCP tools for searching, reading, and writing shared memory
• Project context storage for stable paths, services, ports, and conventions
• Short-lived agent observations with TTL
• HTTP sidecar with bearer-token authentication
• Actor identity derived from token registry, not model-provided fields
• PostgreSQL persistence with pgvector-backed semantic and hybrid search
• Secret rejection for common token/private-key patterns
• Audit events for writes, permission denials, unauthorized calls, and pruning
• Fake JSON store for local development and smoke tests

MCP Tools

• memory_search
• memory_get
• project_context_get
• memory_add
• agent_observation_add
• project_context_set (admin-only)

Search Modes

Search defaults to keyword/full-text mode. PostgreSQL deployments can enable semantic or hybrid mode after backfilling memory_embeddings; see Configuration and Semantic And Hybrid Search.

Guides

• Architecture
• 5-Minute Demo Transcript
• PostgreSQL Quickstart
• 30-Minute Durable Deployment Transcript
• Semantic And Hybrid Search
• Agent Integrations
• Operations
• Backup And Restore
• Security Model
• Release Checklist

Quick Start

Install From Source

git clone https://github.com/zenbordercom/agents-memory-sidecar.git
cd agents-memory-sidecar
npm install
npm run build

Validate the checkout and build output:

node scripts/check-installation.mjs --profile quickstart --pretty

Demo Mode

Demo mode uses the fake JSON store and does not require PostgreSQL, systemd, or production config files:

npm run smoke
npm run http:smoke
npm run http:bridge-smoke

Use the fallback CLI against the fake store:

AGENT_MEMORY_AGENT_ID=local-cli \
AGENT_MEMORY_RUNTIME=local \
AGENT_MEMORY_ROLE=writer \
AGENT_MEMORY_PROJECTS='*' \
node dist/cli.js memory_add '{
  "tenant":"default",
  "project":"demo-app",
  "namespace":"ops",
  "kind":"note",
  "title":"Demo memory",
  "body":"Agents Memory Sidecar demo mode is running with the fake store.",
  "source_type":"manual"
}'

Search it:

AGENT_MEMORY_AGENT_ID=local-cli \
AGENT_MEMORY_RUNTIME=local \
AGENT_MEMORY_ROLE=writer \
AGENT_MEMORY_PROJECTS='*' \
node dist/cli.js memory_search '{
  "tenant":"default",
  "project":"demo-app",
  "query":"demo mode",
  "limit":5
}'

Local HTTP Sidecar Mode

Create a private local token registry:

mkdir -p .local/agents-memory
node scripts/upsert-http-token.mjs \
  --file .local/agents-memory/http-tokens.json \
  --agent-id local-cli \
  --runtime local \
  --role writer \
  --projects '*'

The token script prints a fingerprint only. For local development, load the matching local-cli/local token into your shell from the private registry file:

export AGENT_MEMORY_HTTP_BEARER_TOKEN="$(
  node -e "const fs=require('fs');const r=JSON.parse(fs.readFileSync('.local/agents-memory/http-tokens.json','utf8'));const e=Object.entries(r).find(([,a])=>a.agentId==='local-cli'&&a.runtime==='local');if(!e) throw new Error('local-cli/local token not found');console.log(e[0])"
)"

Start the HTTP sidecar in one terminal:

AGENT_MEMORY_HTTP_TOKENS_FILE="$PWD/.local/agents-memory/http-tokens.json" \
AGENT_MEMORY_HTTP_HOST=127.0.0.1 \
AGENT_MEMORY_HTTP_PORT=18790 \
npm run http:dev

In another terminal, call it through the CLI HTTP backend:

export AGENT_MEMORY_HTTP_BEARER_TOKEN="$(
  node -e "const fs=require('fs');const r=JSON.parse(fs.readFileSync('.local/agents-memory/http-tokens.json','utf8'));const e=Object.entries(r).find(([,a])=>a.agentId==='local-cli'&&a.runtime==='local');if(!e) throw new Error('local-cli/local token not found');console.log(e[0])"
)"

AGENT_MEMORY_BACKEND=http \
AGENT_MEMORY_HTTP_BASE_URL=http://127.0.0.1:18790 \
AGENT_MEMORY_AGENT_ID=local-cli \
AGENT_MEMORY_RUNTIME=local \
AGENT_MEMORY_ROLE=writer \
AGENT_MEMORY_PROJECTS='*' \
node dist/cli.js memory_add '{
  "tenant":"default",
  "project":"demo-app",
  "namespace":"ops",
  "kind":"note",
  "title":"HTTP sidecar demo",
  "body":"The local HTTP sidecar accepts bearer-token memory writes.",
  "source_type":"manual"
}'

Search it:

AGENT_MEMORY_BACKEND=http \
AGENT_MEMORY_HTTP_BASE_URL=http://127.0.0.1:18790 \
AGENT_MEMORY_AGENT_ID=local-cli \
AGENT_MEMORY_RUNTIME=local \
AGENT_MEMORY_ROLE=writer \
AGENT_MEMORY_PROJECTS='*' \
node dist/cli.js memory_search '{
  "tenant":"default",
  "project":"demo-app",
  "query":"HTTP sidecar",
  "limit":5
}'

Durable PostgreSQL Mode

Use PostgreSQL when you want durable shared memory:

AGENT_MEMORY_BACKEND=postgres \
PGDATABASE=agents_memory \
npm run db:migrate

Then run the PostgreSQL smoke test:

npm run postgres:smoke

See PostgreSQL Quickstart for a complete local database setup.

Installation Options

Install the current GitHub release tag:

npm install -g github:zenbordercom/agents-memory-sidecar#v0.2.1

Or install the release tarball:

npm install -g https://github.com/zenbordercom/agents-memory-sidecar/releases/download/v0.2.1/agents-memory-sidecar-0.2.1.tgz

The npm registry package may lag the GitHub release. Check the registry version before using the unpinned npm install path:

npm view agents-memory-sidecar version  # must print 0.2.1 or newer
npm install -g agents-memory-sidecar

The CLI entry points are:

agents-memory --help
agents-memory-mcp
agents-memory-http

• agents-memory: JSON CLI for direct commands and fallback automation.
• agents-memory-mcp: stdio MCP wrapper for agent clients.
• agents-memory-http: local HTTP sidecar.

Quick Start Troubleshooting

• Missing dist/*.js: run npm run build.
• Missing token registry: create one with scripts/upsert-http-token.mjs and set AGENT_MEMORY_HTTP_TOKENS_FILE.
• HTTP connection refused: start agents-memory-http or npm run http:dev, then run node scripts/check-installation.mjs --profile quickstart --check-http --expected-backend fake --pretty.
• permission_denied: check that the bearer token actor has the required role and project access.

Agent Setup

The recommended client pattern is:

1. Store the bearer token in a private env file.
2. Create a small launcher script that sources that env file.
3. Point the agent's MCP config at the launcher.

See Agent Integrations and integrations/*/README.md.

Security Defaults

• Bind the HTTP sidecar to 127.0.0.1.
• Keep full bearer tokens out of Git, chat, logs, and docs.
• Use separate tokens per agent.
• Give normal agents writer, not admin.
• Store stable facts, not secrets or raw .env files.
• Treat model-provided actor fields as untrusted.

See Security Model.

Production Operations

Optional scripts and systemd unit examples are included for local Linux deployments. Review paths, users, groups, database roles, and backup passphrase handling before use.

sudo scripts/install-local.sh

See Operations and Backup And Restore.

Limitations

• Search defaults to keyword/full-text mode. Semantic and hybrid search require stored embeddings and an embedding model or explicit query embedding.
• The project does not replace an agent's internal conversation memory.
• The sidecar is local-first and not designed as a public multi-tenant SaaS API.
• Fresh install automation is intentionally minimal in this version.

What This Is Not

• Not a hosted SaaS API or public internet service.
• Not an agent scheduler or orchestration framework.
• Not a secret manager.
• Not full conversation memory.
• Not a replacement for each agent's native session state.

License

Apache-2.0.