🧬 Companion Memory

Your life, secured locally. A fully private, Personal Digital Twin database and lifelogging engine that ensures your digital history belongs entirely to you.

Status: Companion Memory is in closed preview. Join the waitlist  for early access.

Overview

Companion Memory is the intelligence core of the Companion ecosystem. It runs entirely on your local hardware and acts as a unified personal knowledge base, automatically aggregating data signals from your devices, browser, wearables, and integrated workflows into a single private timeline — your Personal Digital Twin.

Unlike cloud-based memory products, your data never leaves your hardware. The server exposes a local API that Companion Agents query to provide contextually aware suggestions, recall, and guidance.

Key Features

• Automatic ingestion — captures data from browser extensions, desktop applet, wearables, and import tools with no manual tagging
• Unified Explorer — one searchable view of your whole history across List, Gallery, Map, Graph, and Timeline
• Combinable search & filters — free-text + semantic search combined with who / where / when / how filters, sort, and tags
• Saved searches — name and reuse any search you build, and share a read-only link with someone else on your server
• Agent context (MCP + REST) — structured endpoints for Companion Agents to query memory with temporal and contextual filters
• Private by design — zero telemetry, zero cloud sync unless explicitly configured
• Modular connectors — extensible data source plugins for custom integrations

Use Cases

• Recall anything you’ve seen, read, or done — without relying on cloud services
• Give your local AI agents rich, personal context to improve suggestions and task completion
• Build a searchable personal archive of life events, documents, browser history, and media
• Maintain a continuous data log from wearables (Mentra Live, Omi, Mentra) for health and memory analysis
• Power the Spatial Time Machine and Photogram with structured memory data

Architecture

The server ships as a Docker container managed by Companion Hub. It exposes:

• A REST API for data ingestion and retrieval
• An MCP (Model Context Protocol) server for direct agent integration
• A local web UI for browsing your timeline and configuring connectors

Setup

1. Install via Companion Hub

Open Companion Hub, navigate to the App Store, and search for Companion Memory. Click Install.

2. Configure data sources

App hostnames use your configured local domain — .localhost is the default. If one doesn’t resolve on your setup, see Finding Your App’s URL.

After installation, open the Companion Memory web UI at http://companion-memory.localhost. Navigate to Settings → Connectors and enable the sources you want to capture from:

• Browser (requires the Browser Extension)
• Desktop capture (install CI-Applet, sign in to this CI-Server, and optionally add watched folders for file edits)
• Wearables (configure in each wearable’s settings page)
• Manual import (via Import Tools)

3. Connect Companion Agents

In the Hub dashboard, open Agents → Context Sources and add your Companion Memory endpoint. Agents will automatically query it when generating responses.

4. Configure retention policy (optional)

Navigate to Settings → Retention to set data retention windows, storage limits, and automatic pruning rules.

Using the web UI

Most of the time you’ll work with your memory through the local web UI at http://companion-memory.localhost. The whole experience is built around one screen — the Explorer at /memory — that you reshape with search, filters, and views.

The Explorer

The Explorer answers one question — “show me memories that match this” — in five different ways:

A Companion › Memory › {view} breadcrumb at the top hosts the view switcher, with a global search box and a left navigation rail down the side; everything below is the active view. The URL holds the full state of your search (?search=…&view=map&from=…), so any result is a shareable link to someone else on your server.

The default List view groups everything that matches by day (and a No date bucket), each entry tagged with a type icon — person, concept, event, place, question, or file:

The Graph view (the Knowledge Graph) draws the relationships between entities — people, concepts, events, and places — as an interactive node graph. Filter chips toggle node and link types (concept, event, person, place; attended, knows, located_at, related_to), and the 2D/3D switch, neighbor cap, and hop-depth slider control how much of the graph is drawn around the anchored node:

The Gallery view tiles every entity as a card labelled with its type (Person, Concept, Place, Item, Question, Content, Email, SMS) — photo/video events show real thumbnails, and text-only entities show their summary.

The Map view pairs a base map with a synced timeline panel on the left; clusters expand as you zoom, and the Search events in this area button restricts results to the current viewport.

Photo/video events show real thumbnails in List/Gallery/Map; clicking one opens a cross-result lightbox. The same media is preserved when you share the search — see Sharing below.

Search & filters

The search box at the top performs a free-text search across everything you’ve ingested. Switching on the Semantic toggle re-ranks results by meaning rather than keyword match.

When you want to be more precise, the Advanced toggle opens a filter drawer with five combinable dimensions:

• Who — people involved (e.g. “Alex Chen, Maria”)
• Where — places, or “Located only” to limit the map to placed events
• When — a date range with optional times
• How — event types (visited, messaged, called, browsed, …)
• Source — connectors the event came from (gmail, imessage, browser, …)

Plus Sort (Default / Relevance / Newest / Oldest / Name A–Z / Z–A) and Tags. Every filter you add appears as a removable chip above the results so you can see exactly what your search is doing — and tear it back down one chip at a time.

Saved searches

Any search you build can be saved so you can come back to it. In the Explorer toolbar, click Save search — the dialog stores the current query, entity types, tags, and all your active filters (who/where/when/how/sort/semantic/located), so the saved search round-trips the full search.

Saved searches live at /saved-searches. Each card shows:

• A filter-count chip (⚙ N) — hover to see which dimensions are active (Who, Where, When, How, Source, Semantic)
• A Shared badge if the search is currently link-shared
• Edit / Share / Delete actions

Clicking a card opens the Explorer with that search restored — every filter, the right sort, the right view.

Editing a saved search

Click the pencil on any card to open the Edit modal. Below the usual name / description / query / entity types / tags, a Filters section exposes a full editor for the secondary dimensions:

• Who / Where / How / Source — removable chips with a free-text add input
• From / To — date pickers
• Sort — a preset dropdown
• Located only / Semantic — toggles

Editing here keeps the saved search in sync everywhere it runs — including a shared link.

Sharing a saved search

A saved search can be turned into a read-only capability link that someone else on your server can open.

Open the share modal from a card’s share button — or build a search, click Save search, and choose Save & share to do both in one step.

Toggle Link shared to mint an unguessable token. The modal then exposes:

• A share link (/shared/<token>) with a copy button
• Email / Message / Facebook / LinkedIn quick-share buttons
• An iframe embed snippet to drop the search results into another page

The recipient signs into your server and opens the link to a focused, read-only Explorer (List / Gallery / Map) — no edit affordances, no global search, no escape to other parts of the app. The search runs as you (the owner) so the link surfaces only what’s already in your saved search; if they’re signed out when they click, the OIDC login flow brings them back to the same share link automatically.

Capability tokens, signed-in only. A share link grants access only to that one saved search. Toggling sharing off — then on again — rotates the token; the old link stops working. Any viewer still has to be a signed-in user on your server: shares are not anonymous.

Assistant chat

The Chat section turns your memory into a conversational surface: ask a question in natural language and a locally-served model answers grounded in your own entities, citing the people, events, and concepts it drew from. A left rail keeps your recent threads, and the model picker in the header selects which local model answers.

Feed

The Feed is the home surface: an Actions carousel where Companion asks you a question or surfaces something that needs your input, and an Insights & Summaries stream the server generates as it learns from your memory.

Mobile

The Explorer is responsive, and a shared search opens on a phone too — the view tabs render inline (the global header collapses), and the map uses a touch-optimised mobile layer.

API Access

Companion Memory exposes a local REST and GraphQL API. Requests authenticate with an API key that you create in the web UI under Settings → API Keys — the full key is shown once at creation, and you send it as an x-api-key header.

REST

# Ingest events — up to 1000 per request, deduplicated on the provenance
# triple (source_type, source_system, source_id); source_type defaults to
# "capture" when omitted, so re-POSTing this body counts as a duplicate
curl -X POST http://companion-memory.localhost/api/v1/events \
  -H "x-api-key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "events": [
          {
            "source_system": "my-app",
            "source_id": "meeting-2026-04-01",
            "kind": "note",
            "occurred_at": "2026-04-01T10:00:00Z",
            "title": "Meeting with team",
            "payload": {}
          }
        ]
      }'

Searching is a GraphQL operation rather than a REST route — see below.

GraphQL

The graph of entities, events, files, people, places, and summaries is available through a single GraphQL endpoint at /api/graphql:

# Recent events
curl -X POST http://companion-memory.localhost/api/graphql \
  -H "x-api-key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ events(first: 5) { edges { node { id title startTime } } } }"}'
 
# Search — results are a union, so select per type with inline fragments
curl -X POST http://companion-memory.localhost/api/graphql \
  -H "x-api-key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ search(input: {query: \"your query\", first: 5}) { totalCount edges { node { __typename ... on EventType { id title startTime } } } } }"}'

API Playground (GraphiQL)

Companion Memory ships the GraphiQL  IDE so you can explore the schema and run queries interactively — no external tooling required.

1. Create an API key — in the web UI, open Settings → API Keys, click ＋, name the key, and copy it (it’s shown only once).
2. Open the playground — go to Settings → GraphiQL. It opens the IDE in a new tab (served at /api/graphiql).
3. Authenticate — paste your key into the API key field in the top bar and click Save. The status turns to key active and the key is stored in your browser and attached (x-api-key) to every request. Use Clear to remove it.
4. Explore & run — click Docs (top-right) to browse the schema, write a query in the editor, and press the ▶ button to run it. Results appear on the right.

# Your 20 most recent events
query RecentEvents {
  events(first: 20) {
    edges {
      node {
        id
        title
        startTime
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

List fields use cursor pagination (first/after), so pass the endCursor from pageInfo back as after to page through results. The playground follows GraphiQL’s own light/dark toggle:

Agent Integration (MCP)

Companion Memory speaks the Model Context Protocol over Streamable HTTP at /api/mcp, so any MCP-capable client — Claude Code, Cursor, OpenCode, OpenClaw, Hermes — can use your memory as a tool source. Authenticate with the same API key. Companion Memory accepts it either as an x-api-key header or as Authorization: Bearer — prefer Authorization: Bearer, since Companion Hub accepts only that form and one pattern then covers both servers.

{
  "mcpServers": {
    "companion-memory": {
      "type": "http",
      "url": "http://companion-memory.localhost/api/mcp",
      "headers": {
        "Authorization": "Bearer <your API key>"
      }
    }
  }
}

Keep the "type": "http" line. Clients that infer the transport from the URL tolerate its absence, but Claude Code does not — it skips an entry that has a url and no type, and the server simply never appears.

Key scopes

Scopes decide both whether you connect and which tools you see:

A key holding mcp but not intents is the trap: it authenticates, the session opens, and the tool list comes back empty — which most agents surface as “this server has no tools” rather than as a permissions problem. Give a scope-limited key both mcp and intents.

GraphQL-derived tools are never advertised to a scope-limited key, whatever its scopes; they require a full-access key. Requests carrying no key at all are rejected with 401.

Troubleshooting

Ingestion pipeline not running Check the container logs in Companion Hub under the Companion Memory app. Ensure the source connector has the correct API key or token configured.

Search returning no results Indexing runs asynchronously after ingestion. If data was just added, wait a few minutes and try again. If the problem persists, trigger a manual re-index from Settings → Maintenance → Re-index.

High disk usage Navigate to Settings → Storage to see a breakdown by data source. Reduce retention periods or exclude high-volume sources to reclaim space.

Agent not using memory Verify the MCP endpoint responds from within the Hub network. An unauthenticated request should return 401 — that confirms routing and auth are both live:

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://companion-memory.localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Read the code you get back:

• 405 — the URL is wrong. The MCP server is at /api/mcp, not /mcp.
• 401 with a key attached — the key is unknown or revoked. Mint a new one under Settings → API Keys.
• 403 — the key is valid but lacks the mcp scope.

If the endpoint answers correctly and the agent still ignores memory, check in this order:

1. The agent reports the server as connected but empty. The key is missing the intents scope — see Key scopes. This is the most common cause.
2. Claude Code shows no such server at all. Its entry is missing "type": "http".
3. Otherwise, check the agent’s context source configuration.

Shared link returns “This shared search isn’t available” The token may have been revoked. Sharing is one of Not shared / Link shared; turning sharing off — then on again — issues a new token, and the old link stops working. Ask the owner to share again; their share modal shows the current link. The link also requires the viewer to be a signed-in user on the same server (shares are signed-in-only, not anonymous).

Shared gallery is blank The owner’s photo/video event needs to have its media file ingested too (not just the timeline event), and the shared search must include event and file entity types. Open the search via the owner’s Edit modal and confirm the entity types and filters.

Links

• ci.computer/software 
• Browser Extensions
• Import Tools
• Desktop Applet