Concepts

Memcone is a persistent memory layer for AI applications. This page explains the internal model so the API makes complete sense.

Projects, global memory, and API scopes

Three surfaces answer three different questions:

| Dashboard route | What it is | Relationship to primitives | |---|---|---| | Projects hub — open a card → /dashboard/projects/<id> | Coding-agent memory: identity, rules, decisions, dual-lane confirmed vs AI notes, scoped to one repo/project | Feeds memcone.context / compiled MCP output for that project; complements semantic remember / recall | | Global memory | Same dual-lane model with no project id — user-wide defaults that merge into every linked project | Explicit projectId: null rows; still observability-first like project memory | | API scopes | Beliefs stored under scopeId strings from POST /v1/remember | Pure remember / recall / context retrieval pipeline |

Your active project (CLI link, dashboard Projects) decides MCP scope resolution when both project state and semantic memory apply.

How memory is stored

When you call /v1/remember, your raw text isn't stored as-is — it's parsed into discrete, standalone facts called memories:

Input:  "The user says they work at a startup building dev tools and prefer TypeScript"

Stored as:
  → "works at a startup"
  → "startup builds developer tools"
  → "prefers TypeScript"

Input:  "The user says they work at a startup building dev tools and prefer TypeScript"

Stored as:
  → "works at a startup"
  → "startup builds developer tools"
  → "prefers TypeScript"

Each item is embedded, deduplicated, and scored. Identical facts reinforce — they don't stack.

The memory pipeline

Input text
    ↓
Extraction (LLM)
    ↓
Embedding
    ↓
Contradiction check → decay conflicting facts
    ↓
Store / reinforce
    ↓
Retrieval (context / recall)
    ↓
Decay over time if not reinforced

Input text
    ↓
Extraction (LLM)
    ↓
Embedding
    ↓
Contradiction check → decay conflicting facts
    ↓
Store / reinforce
    ↓
Retrieval (context / recall)
    ↓
Decay over time if not reinforced

Formation

When /v1/remember is called, an LLM extracts discrete facts. Each is embedded and inserted. If the same fact appears again, its reinforcement_count increments instead of creating a duplicate.

Reinforcement

Every subsequent call with a similar fact increases that item's reinforcement_count. Frequently-confirmed facts become stronger and rank higher in retrieval.

Contradiction resolution

When a new fact is stored, Memcone searches for semantically nearby items that contradict it. Conflicting items have their reinforcement_count decremented — they don't disappear, they weaken. Over time they decay out of retrieval naturally.

// Before
"user prefers JavaScript"  (reinforcement_count: 3)

// After remembering "user switched to TypeScript"
"user prefers JavaScript"  (reinforcement_count: 2)  ← weakening
"user switched to TypeScript"  (reinforcement_count: 1)  ← forming

// Before
"user prefers JavaScript"  (reinforcement_count: 3)

// After remembering "user switched to TypeScript"
"user prefers JavaScript"  (reinforcement_count: 2)  ← weakening
"user switched to TypeScript"  (reinforcement_count: 1)  ← forming

Decay

Facts that haven't been reinforced recently rank lower in retrieval — even without explicit contradiction.

The strength formula

Every stored item has a live strength score:

strength = reinforcement_count / ((1 + days_elapsed) × (1 + seq_lag × 0.1))

strength = reinforcement_count / ((1 + days_elapsed) × (1 + seq_lag × 0.1))

| Variable | Meaning | |---|---| | reinforcement_count | Times this belief has been confirmed | | days_elapsed | Days since belief was created | | seq_lag | How far back in sequence it was last touched |

This encodes: recency decay × reinforcement amplification × sequence relevance. You can see live strength scores under API scopes.

Scopes

Every call takes a scopeId — a string you control. Beliefs are fully isolated within a scope.

scopeId: "user_123"               # per-user memory
scopeId: "user_123:project_abc"   # per-user, per-project
scopeId: "org_456"                # org-wide shared memory
scopeId: "session_xyz"            # ephemeral session memory

scopeId: "user_123"               # per-user memory
scopeId: "user_123:project_abc"   # per-user, per-project
scopeId: "org_456"                # org-wide shared memory
scopeId: "session_xyz"            # ephemeral session memory

Retrieval

When you call /v1/context or /v1/recall, the system:

1. Embeds the query
2. Searches by cosine similarity
3. Ranks results by strength (not just similarity)
4. Compresses top results into a context string

The combination of semantic similarity + strength ranking surfaces the most relevant and trusted beliefs — not just keyword matches.

Retrieval tracing

Every /v1/context and /v1/recall call is logged with which beliefs were retrieved, their similarity and strength scores, and cache status. Inspect in the Retrieval Traces dashboard or via GET /v1/traces. This is what makes the system debuggable — you can always see why an AI responded the way it did.

Turbo Cache

/v1/context responses are cached per scopeId + task pair. Cache hits are typically under 20ms p50 and cost 1 compute unit; cache misses run full retrieval (often ~200ms) and cost 3–5 units — compare hit latency to miss latency, not to an always-on vector query. The cache invalidates automatically when /v1/remember is called for the same scope.

See Turbo Mode for details.

Confirmed memory vs AI notes (CLI + MCP + dashboard)

For coding agents, Memcone keeps two lanes so trust stays clear:

• Confirmed memory — things you or the user stated explicitly. Authoritative; not overwritten by inference.
• AI notes — session summaries and inferred progress. Helpful but fallible; they expire after 60 days unless you promote them to confirmed memory.

The REST /v1/* surface still accepts plain text per scopeId (no schema you design). Dual-lane controls how the dashboard and MCP store project-scoped facts alongside that semantic memory.