ti

A Unified, Shareable Memory Layer for Every AI App You Use

Your tools know a lot about you — but they don’t talk to each other. Cursor remembers different things than Claude Desktop; Windsurf knows about the repo you opened yesterday; a Gemini CLI scratchpad holds fragments you’ll never see again. Core fixes that. It’s a local-first, shareable memory server that sits beside your editors and agent tools, giving them a common brain: one search, one history, one place to store and recall what matters. It’s built to plug into modern agent clients (Cursor, Claude Desktop & Claude Code, Gemini CLI, Windsurf, AWS’s Kiro, VS Code, Cline) so context moves with you instead of getting stranded per app.

This article explains what Core is, why a memory layer is essential, how it works, and how to run it — locally for yourself or in a small team. By the end, you’ll have Core running, connected to your favorite tools, and already remembering useful things on your behalf.

What Core Is (and why you want it)

Core is a lightweight server + CLI that provides three things:

1. A unified memory model — Drop in notes, facts, decisions, snippets, credentials metadata, run logs, and “what we learned” summaries. Everything is timestamped, tagged, and attributed to its source tool or agent.
2. Smart recall — Retrieve by natural-language query or structured filters. Core blends semantic similarity, recency, and graph relationships to surface the right memory at the right time.
3. Open interfaces — It speaks MCP (Model Context Protocol) for agent/IDE integration and also exposes a clean HTTP API + CLI. That’s how it plugs into Cursor, Claude Desktop/Code, Gemini CLI, Windsurf, AWS Kiro, VS Code, and Cline without bespoke adapters.

Why this matters: Today’s agents are powerful but forgetful. Context fragmentation costs time, spawns duplicate work, and makes assistants inconsistent. A shared memory turns every tool into a participant in one ongoing conversation.

The Memory Model (built for humans and agents)

Core treats memory as first-class data with opinions that actually help:

• Workspaces & scopes — Keep personal, team, and project memory separate. Agents query only what they’re allowed to see.
• Types — note, fact, decision, preference, snippet, doc_chunk, run_log, tool_context. Different types get different default TTLs and ranking behavior.
• Provenance — source_app, source_user, source_url, and hash for deduplication/audit.
• Tags & topics — Free-form tags; topics are auto-expanded via embeddings to cluster related memories.
• Lifespan controls — ttl, pin (never expire), expires_at, and forget() to comply with “right to forget” in seconds.
• Graph edges — Link memories (supports, contradicts, derived_from, similar_to) so Core can expand a recall query into the right surrounding context.
• Attachments — Reference blobs (images, files) while keeping text-first summaries Agent-friendly.

Under the hood, Core uses a vector index, a temporal store, and a lightweight knowledge graph. A multi-signal ranker blends them so you don’t have to think about “search logic” — you just ask.

How Core plugs into your tools

Core is designed around MCP for agent and IDE clients:

• Editors/Agents: Cursor, Claude Desktop & Claude Code, VS Code (via MCP bridge), Windsurf, Cline, Gemini CLI, and AWS Kiro can connect to Core as an MCP server.
• Workflows: “Save this as a fact,” “Recall what we decided about auth,” “What was the staging URL?”, “Summarize the last three runs,” or “Rehydrate all context about the billing service.”

Because the interface is standard, swapping tools doesn’t cost you your memory. Your assistant in one app can benefit from what you taught another yesterday.

Typical things Core remembers (and retrieves instantly)

• Preferences — “Use pnpm,” “tabs over spaces,” “prefer FastAPI for quick services.”
• Project state — “Staging DB URL,” “how to run migrations,” “commands we used to fix build #482.”
• Documentation shards — Key paragraphs from READMEs, ADRs, API schemas — stored as doc_chunk with the original source.
• Decisions — “We chose Postgres over Dynamo due to analytics joins.”
• Snippets — “JWT middleware we like,” “Helm template for ingress,” “common LangChain initialization.”
• Run notes — “Benchmark on M3 Max: 312 req/s with worker=8.”
• Credentials metadata — Not the secret itself, but where it lives and how to rotate it.

Installing and running Core

Commands below assume a Unix-like shell. Names are representative; adjust to your package manager or binary path.

Option A — One-liner with the CLI (local dev)

# Install the Core CLI (local user)
npm i -g @heysol/core
# Initialize config and local storage
core init
# Start the server (opens on localhost:7077 by default)
core serve

What you get: a local Core server with a default workspace (personal), a storage directory (~/.core), and an API key printed once.

Option B — Docker (easy, reproducible)

docker run -d --name core \
  -p 7077:7077 \
  -e CORE_API_KEY=dev-key \
  -e CORE_STORAGE_DIR=/data \
  -v $HOME/.core:/data \
  ghcr.io/redplanethq/core:latest

Option C — Small team deploy (Docker Compose + Postgres)

services:
  core:
    image: ghcr.io/redplanethq/core:latest
    ports: ["7077:7077"]
    environment:
      CORE_API_KEY: ${CORE_API_KEY}
      CORE_DB_URL: postgres://core:core@db:5432/core
      CORE_EMBEDDINGS: "openai"     # or "local"
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    volumes:
      - ./core-data:/data
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: core
      POSTGRES_USER: core
      POSTGRES_PASSWORD: core
    volumes:
      - ./pg-data:/var/lib/postgresql/data

Bring it up with docker compose up -d.

Local-first by default. You can also use a built-in SQLite store if you don’t want Postgres.

Connecting Core to your apps

Connect as an MCP server (Cursor, Claude Desktop/Code, Windsurf, VS Code, Cline, Gemini CLI, AWS Kiro)

Most MCP-aware clients let you add a custom MCP server. Choose command mode and point it to Core:

• Command: core mcp --stdio
  (Alternatively: core mcp --port 3920 if your client prefers TCP.)
• Env: set CORE_URL=http://localhost:7077 and CORE_API_KEY=… so the MCP process can talk to the Core server.

After adding, your agent should expose tools such as:

• memory.upsert, memory.recall, memory.forget, memory.queryGraph, memory.pin, memory.import
• workspace.list, workspace.switch, topic.suggest

From that point, you can say things like:

“Save: Our production S3 bucket is s3://acme-prod-artifacts.”
“Recall the last decision about our auth provider.”
“Find snippets related to ‘retry + axios’.”

Using the HTTP API & CLI directly

Save a memory

curl -X POST "http://localhost:7077/v1/memories" \
  -H "Authorization: Bearer $CORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "personal",
    "type": "fact",
    "text": "We use pnpm and Node 20 in the monorepo.",
    "tags": ["tooling","node"],
    "source": {"app":"cursor","user":"me"},
    "ttl": "365d"
  }'

Recall by question

curl -X POST "http://localhost:7077/v1/recall" \
  -H "Authorization: Bearer $CORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "personal",
    "query": "How do I run DB migrations locally?",
    "limit": 8
  }'

Pin / forget

core memory pin "billing-runbook"
core memory forget --id mem_01HXYZ123

Import docs as chunks (RAG-friendly)

core import docs ./docs --workspace project-billing --tag docs

Core extracts text, splits into semantically coherent chunks, embeds, and stores provenance (path + git hash).

Ranking & retrieval you don’t have to babysit

Core’s recall engine blends multiple signals:

• Semantic similarity — Embeddings turn your query into geometry.
• Temporal weighting — Newer memories rank higher unless pinned.
• Graph expansion — If a memory is deeply connected to the query topic, its neighbors are pulled along.
• Type-aware boosts — A decision often outranks a random note; a snippet may outrank a generic paragraph.

You can override behavior with query hints like type:snippet, tag:infra, since:30d, or expand:2.

Privacy, safety, and compliance features

• Local-first storage with optional encryption at rest.
• “Right to forget” is instantaneous — forget() removes the record, its embeddings, and graph edges.
• Provenance & audit — Every write includes who/what/when.
• Scopes & RBAC — Readers vs writers; agent-only scopes for tool context; personal vs team workspaces.
• PII guards — Heuristics and allow-lists/deny-lists to avoid saving secrets or sensitive tokens as plain text.
• Export — One-command JSONL export per workspace for backups or migration.

Team patterns that actually work

• Per-project workspaces with shared read/write; personal workspace for preferences.
• Save meeting outcomes as decision plus a linked fact that encodes the “how.”
• In reviews, use Core to recall past tradeoffs instead of relitigating them.
• Attach links not secrets: “API key stored in 1Password vault ‘Team Dev’, item ‘Acme Staging OpenAI’.”

Troubleshooting & ops tips

• If an editor can’t find Core, run core mcp --stdio manually and watch logs.
• High-latency recall? Switch embeddings to a local model for dev; use a hosted provider for prod.
• Many small files? Use the CLI importer so doc chunks stay coherent and deduped.
• Back up ~/.core (or your DB) nightly. Consider object storage for attachments.

Conclusion

Agents are finally powerful what they’ve lacked is memory that follows you. Core gives your tools a common, privacy-respecting place to remember preferences, decisions, snippets, and docs, and to recall them instantly — no matter which app you’re in. The target goal is simple and ambitious: one brain for all your AI assistants, local-first, shareable when you want, and easy to wire in.

Spin it up, connect one client, save three useful facts, and ask your next assistant to recall them. You’ll feel the difference the very next time you open your editor.