# Awareness Memory Protocol v0.1

**Status:** Draft
**Version:** 0.1
**Date:** 2026-10-29
**Canonical:** https://awareness.market/en/protocol
**Reference implementation:** https://github.com/everest-an/Awareness-SDK
**System card:** https://awareness.market/benchmarks/awareness-system-card-v0.1.md
**Contact:** e@awareness.market

---

## 1. Scope

Awareness Memory Protocol (AMP/0.1) defines a small set of memory operations for AI agents over MCP, with a local-first storage model and an optional cloud sync path.

It is a **profile over MCP**: the tool names, input shapes, and semantics below are the contract. The transport is MCP (Streamable HTTP); REST and the SDK expose the same operations.

The protocol is intentionally narrow:

- It does not define a model, an agent runtime, or a prompt format.
- It does not require a specific vector database or embedding model.
- It does not require cloud storage, an account, or a vendor.
- It does not define billing, marketplace, or agent hiring. Those are product surfaces, not memory primitives.

The goal is portability: a memory written by one conforming implementation should be exportable and readable by another.

## 2. Design principles

1. **Local-first by default.** Memory is stored on the user's machine in human-readable Markdown with a local index. Cloud is optional.
2. **Agent-agnostic.** Any MCP-compatible client can use the same memory: Claude Code, Cursor, Codex, Windsurf, Cline, Copilot, Zed, JetBrains, OpenClaw, and others.
3. **Structured, not just vector.** The protocol carries knowledge cards, tasks, skills, graph facts, and rules in addition to raw text.
4. **Zero-LLM retrieval.** Recall is a retrieval operation, not a generative call. Implementations may use embeddings, full-text search, graph lookup, or a combination.
5. **No lock-in.** Memory can be exported as Markdown + JSON. Import is a first-class operation.
6. **Least privilege.** Agents read and write only within an explicit scope. Secrets are out of scope.

## 3. Terms

- **Workspace:** a project-level memory boundary, usually a repository. Stored under `<project>/.awareness/`.
- **Scope:** a namespace within a workspace. Common scopes: `project`, `agent:<role>`, `user:<id>`, `session:<id>`.
- **Memory item:** a raw recorded event or note.
- **Knowledge card:** a structured unit extracted from memory items (decision, workflow, pitfall, risk, action item, skill, preference, etc.).
- **Session:** a bounded agent interaction. Used for recall expansion and history.
- **Task:** a unit of work with a status and owner.
- **Skill:** a reusable procedure or capability.
- **Agent profile:** the role and capabilities of an agent in a multi-agent workspace.
- **Graph fact:** a typed relationship between entities.
- **Rule:** an instruction injected into the agent's configuration (for example `CLAUDE.md` or `.cursor/rules/`).

## 4. Operations

Every conforming MCP server MUST expose these four tools. Additional tools MAY exist.

### 4.1 `awareness_init`

Loads the minimum context needed to start a session.

**Input (all optional):**

```json
{
  "workspace": "string",
  "scope": "string",
  "agent_role": "string",
  "detail": "summary | full"
}
```

**Output:**

```json
{
  "workspace": "string",
  "scope": "string",
  "rules": ["string"],
  "open_tasks": ["Task"],
  "knowledge": ["KnowledgeCard"],
  "skills": ["Skill"],
  "agent": "AgentProfile | null",
  "as_of": "ISO-8601"
}
```

**Semantics:**

- MUST be idempotent for the same workspace, scope, and agent role.
- MUST return open tasks and active rules before returning large knowledge payloads.
- SHOULD return summaries by default; `detail: "full"` may return complete cards.

### 4.2 `awareness_recall`

Retrieves relevant memory for the current task.

**Input:**

```json
{
  "query": "string",
  "workspace": "string",
  "scope": "string",
  "mode": "hybrid | precise | session | structured | auto",
  "limit": 8,
  "detail": "summary | full",
  "filters": {
    "types": ["decision", "workflow", "pitfall", "risk", "action_item", "skill", "preference"],
    "agent_role": "string",
    "since": "ISO-8601",
    "until": "ISO-8601"
  }
}
```

**Output:**

```json
{
  "results": [
    {
      "id": "string",
      "type": "knowledge_card | memory_item | graph_fact | task | skill",
      "title": "string",
      "summary": "string",
      "content": "string | null",
      "score": 0.0,
      "source": {
        "workspace": "string",
        "session": "string | null",
        "created_at": "ISO-8601",
        "updated_at": "ISO-8601"
      },
      "evidence": ["string"]
    }
  ],
  "mode_used": "string",
  "truncated": false
}
```

**Semantics:**

- MUST NOT require a generative model call to retrieve results.
- MUST be deterministic enough to reproduce a result set for the same index and query.
- `hybrid` SHOULD combine keyword and semantic signals; `structured` MUST use only structured fields.
- `detail: "summary"` SHOULD return compact cards; full content is opt-in.
- Results MUST be scoped; cross-scope recall requires an explicit scope or an authorized workspace query.

### 4.3 `awareness_record`

Writes memory. The operation is a discriminated union.

**Common input:**

```json
{
  "workspace": "string",
  "scope": "string",
  "agent_role": "string",
  "op": "remember | remember_batch | backfill | ingest | update_task | submit_insights"
}
```

**`remember`:**

```json
{
  "op": "remember",
  "content": "string",
  "type": "decision | problem_solution | workflow | pitfall | risk | action_item | skill | preference | note",
  "metadata": {},
  "source": { "session": "string | null", "url": "string | null" }
}
```

**`remember_batch`:** an array of `remember` items, used at session end.

**`backfill`:** imports past conversations or notes with timestamps.

**`ingest`:** bulk data with a source and optional chunking hints.

**`update_task`:**

```json
{
  "op": "update_task",
  "task_id": "string",
  "status": "open | claimed | doing | blocked | done | failed",
  "owner": "string | null",
  "note": "string | null"
}
```

**`submit_insights`:** structured cards extracted by the client, with evidence.

**Output:**

```json
{
  "ok": true,
  "recorded": ["string"],
  "skipped": ["string"],
  "conflicts": [
    {
      "existing_id": "string",
      "incoming_id": "string",
      "reason": "contradiction | duplicate | superseded"
    }
  ]
}
```

**Semantics:**

- MUST deduplicate identical content within a scope.
- MUST NOT silently overwrite a conflicting card; conflicts are returned to the caller.
- Writes MUST be durable before returning `ok`.
- The protocol does not define an LLM extraction step; extraction is an implementation detail.

### 4.4 `awareness_lookup`

Fast structured lookup for tasks, rules, and known fields.

**Input:**

```json
{
  "workspace": "string",
  "scope": "string",
  "kind": "context | tasks | knowledge | risks | session_history | timeline | handoff | rules | graph | agents",
  "id": "string | null",
  "status": "string | null",
  "agent_role": "string | null",
  "limit": 50
}
```

**Output:** a typed object for the requested `kind`. Implementations MUST return an empty result rather than an error when a scope has no matching records.

**Semantics:**

- `lookup` is for structured queries, not semantic search; use `recall` for relevance ranking.
- `lookup` SHOULD be faster than `recall` and MUST not call an LLM.

## 5. Data model

### 5.1 Memory item

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | Stable within a workspace |
| `workspace` | string | yes | Project identifier |
| `scope` | string | yes | Namespace |
| `type` | enum | yes | Raw event category |
| `content` | string | yes | Plain text or Markdown |
| `created_at` | ISO-8601 | yes | UTC |
| `updated_at` | ISO-8601 | yes | UTC |
| `source` | object | no | Session, URL, tool |
| `metadata` | object | no | Implementation-specific |

### 5.2 Knowledge card

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | Stable |
| `type` | enum | yes | `decision`, `problem_solution`, `workflow`, `pitfall`, `risk`, `action_item`, `skill`, `preference`, `fact` |
| `title` | string | yes | Short, human-readable |
| `summary` | string | yes | Compact recall form |
| `content` | string | yes | Full card |
| `evidence` | string[] | no | Pointers to source items |
| `confidence` | number | no | 0..1; implementation-specific |
| `status` | enum | no | `active`, `superseded`, `archived` |
| `created_at` / `updated_at` | ISO-8601 | yes | UTC |

### 5.3 Task

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | Stable |
| `title` | string | yes | Short |
| `status` | enum | yes | `open`, `claimed`, `doing`, `blocked`, `done`, `failed` |
| `owner` | string | no | Agent role or user |
| `priority` | string | no | Implementation-specific |
| `lease_until` | ISO-8601 | no | For claimed tasks |
| `created_at` / `updated_at` | ISO-8601 | yes | UTC |

### 5.4 Graph fact

```json
{
  "id": "string",
  "subject": "string",
  "predicate": "string",
  "object": "string",
  "valid_from": "ISO-8601 | null",
  "valid_to": "ISO-8601 | null",
  "source": "string"
}
```

Graph facts are bi-temporal: `valid_from`/`valid_to` describe when the fact was true; `created_at` describes when it was recorded.

## 6. Storage and export

- Local default: Markdown files under `.awareness/`, plus a local SQLite index.
- Implementations MAY add embeddings, full-text indexes, or a graph store, as long as the exported data remains portable.
- Every conforming implementation MUST support a lossless export:

```
.awareness/
  memory/
    <id>.md
  cards/
    <id>.md
  tasks/
    <status>/<id>.md
  skills/
    <id>.md
  graph/
    facts.jsonl
  manifest.json
```

`manifest.json` MUST include the protocol version, workspace, export timestamp, counts, and checksums.

## 7. Local/cloud boundary

- Local mode MUST work without an account and without a network connection.
- Cloud sync is opt-in. When enabled, the cloud is a replica, not the only copy.
- A conforming cloud implementation MUST provide tenant isolation, encryption in transit, and a documented retention policy.
- The protocol does not define authentication. Implementations MUST use their existing auth (local daemon token, API key, OAuth) and MUST NOT put secrets into memory records.

## 8. Error model

```json
{
  "ok": false,
  "error": {
    "code": "invalid_scope | not_found | conflict | rate_limited | unavailable | unauthorized",
    "message": "string",
    "retryable": false
  }
}
```

- `conflict` MUST include the conflicting record IDs.
- `rate_limited` SHOULD include a retry hint.
- Implementations MUST NOT return a successful empty result when the underlying store is unavailable.

## 9. Conformance

A conforming implementation:

1. Exposes the four operations over MCP with the schemas above.
2. Preserves scope isolation.
3. Supports a lossless export.
4. Returns conflicts explicitly.
5. Works locally without a network connection.
6. Documents its embedding model, index, and retention behavior.

Reference implementation: `npx @awareness.market/setup` (local daemon + MCP server).
SDK: https://github.com/everest-an/Awareness-SDK

## 10. Versioning

- `v0.x` is a draft; breaking changes are allowed with a new minor version.
- Additive fields are allowed without a version bump if old clients can ignore them.
- A future `v1.0` will freeze the four operation shapes and the export manifest.

## 11. Open questions

- Should rules be a first-class record type or a projection of cards?
- How should multi-workspace recall be authorized?
- What is the minimum graph schema for portability?
- How should memory be redacted on export?

Feedback: e@awareness.market
