Connect an agent
to your shared memory.

---
description: Use the teamshared MCP server as persistent cross-session memory.
alwaysApply: true
---

# teamshared Memory Protocol

The `teamshared` MCP server is your durable brain across sessions and repos.
Bearer token sets write attribution; do not pass `agent` unless you intentionally
override it or narrow a read filter.

## Core workflows

### Recall first

Before any non-trivial request (architecture, debugging, "how do we…", past work),
call `memory_recall` with the user's query. Ground answers in hits; cite them.

- Omit `scope` to search all pillars (default).
- `scope=["procedural"]` for "how do we usually…".
- `scope=["strategic"]` for vision, mission, OKRs, and initiatives.
- `scope=["episodic"]` for "what did we do on X?".
- `scope=["semantic"]` for stable facts and preferences.
- `scope=["working"]` only when you need the caller's open session turns.
- For code/repo-specific work, pass `repo=<workspace-slug>` and/or
  `github=<owner>/<repo>` to softly boost scoped memories (nothing is hidden).

If recall is empty, say so before answering from priors.

### Code work: resolve `repo` and `github`

When the user is working on code in a git checkout:

1. **Workspace slug** — run `git rev-parse --show-toplevel` (or use the Cursor
   workspace root), strip a leading `/`, replace `/` with `-`. Pass as `repo=`
   on `memory_recall`, `memory_remember`, and `memory_session_open` (same slug
   as `memory_state` and plugin hooks).
2. **GitHub repo** — when `command -v gh` succeeds, run
   `gh repo view --json nameWithOwner` from the repo root and pass
   `github=<nameWithOwner>` (e.g. `xhad/teamshared`). Stable across machines;
   the server stores `github:<owner>/<repo>`. Optional `subject=<nameWithOwner>`.
3. **Never** use `owner/repo` as `repo=` (slashes are invalid for workspace slugs).
4. If an MCP call fails with invalid JSON mentioning `repo`, omit `repo` and use
   `github=` (and/or explicit `tags`) instead; retry.

### Remember durable things

Call `memory_remember(content, kind=...)` for things still true next week:

| Signal | `kind` |
|---|---|
| "I prefer / always / never …" | `preference` |
| Stable repo fact | `fact` |
| One-off event worth logging | `event` |
| Misc working note | `note` |

Optional: `subject`, `tags`. For code/repo-specific memories, pass
`repo=<workspace-slug>` and/or `github=<owner>/<repo>`; omit both for
cross-cutting preferences. Do **not** use `memory_remember` for playbooks —
use `memory_procedure_set`.

### Sessions for multi-turn work

For tasks spanning ~3+ turns:

1. `memory_session_open(topic=<short label>)` — keep `session_id`.
2. `memory_session_append(session_id, role, content)` after each turn
   (`user` | `assistant` | `tool` | `system`).
3. `memory_session_close(session_id, distill=true)` when done or pivoting.

Skip sessions for one-shot questions.

### Read vs write scoping

- **Shared brain (default):** `memory_recall` and `memory_episodes_list` return
  every agent's durable memories unless you pass `agent=` to narrow.
- **Caller-scoped working memory:** recall always includes the caller's own
  session turns; durable pillars are not filtered by caller unless `agent=` is set.
- **Writes:** `memory_remember`, `memory_session_*`, `memory_procedure_set`, and
  `memory_graph_relate` attribute to the bearer token unless `agent=` overrides.

## Human console (`/app`)

teamshared has a web console for humans at `<server>/app`
(e.g. https://teamshared.com/app). When a teammate asks how to *see* the
memory, sign in, get an API key, onboard, or manage their team, point them there —
these are human/browser actions, not MCP tools:

- **Sign in:** any email + a one-time passcode (no password). First sign-in
  creates that email's own private org; they can create more orgs and switch
  between them from the header.
- **Memory wiki** (`/app/wiki`): semantic facts, the episodic timeline, and
  playbooks rendered as a browsable, human-readable knowledge base.
- **Manage:** agents, **API keys** (`tsk_…`, the bearer token MCP/agents use),
  people (add a teammate by email), approvals, and capture consent.

A fresh self-serve org starts empty and isolated; joining the shared team brain
is an admin action (People → add member). The public, no-auth status page is at
`<server>/memory`.

## Tool reference

### `health`

Probe server liveness and dependencies. Returns
`{"status": "ok"|"degraded", "components": {...}}` covering redis, postgres, and
the memory/LLM backends (semantic, distiller, curator, graph, ollama).
Use when MCP seems broken or before blaming empty recall on missing data.
Never run shell commands to inspect `TEAMSHARED_URL` / `TEAMSHARED_TOKEN` env
vars — MCP is configured inline in the client config, not the agent shell. If
MCP looks down, call `health`, not `echo`.

### `memory_recall`

Hybrid search across semantic, episodic, procedural, and working pillars.

| Param | Use |
|---|---|
| `query` | Natural-language search (required) |
| `scope` | Subset of pillars; omit = all five |
| `k` | Max records (1–50, default 8) |
| `time_range` | Optional bounds for episodic/working hits |
| `agent` | Optional filter to one agent's durable writes |
| `repo` | Optional workspace slug; soft-boosts `repo:<slug>` tags (nothing hidden) |
| `github` | Optional `owner/repo`; soft-boosts `github:<owner>/<repo>` tags |

Returns `records` with pillar, agent, timestamps, and content for citation.
For code work, pass `repo=<workspace-slug>` and/or `github=<owner>/<repo>`.

### `memory_remember`

Write semantic or episodic memory.

| Param | Use |
|---|---|
| `content` | Text to store (required) |
| `kind` | `fact` \| `preference` \| `event` \| `note` (default `note`) |
| `subject` | Optional entity the memory is about |
| `tags` | Optional string list |
| `agent` | Optional attribution override |
| `repo` | Optional workspace slug → `repo:<slug>` tag |
| `github` | Optional `owner/repo` → `github:<owner>/<repo>` tag (portable) |

Routing: `event` → episodic; others → semantic. Rejects `kind=procedure`.
For code work, pass `repo=` and/or `github=`; omit both for cross-cutting facts.

### `memory_session_open` / `memory_session_append` / `memory_session_close`

Working-memory buffer in Redis for the current task.

| Tool | Key params |
|---|---|
| `memory_session_open` | `topic`, optional `ttl`, `agent`, `repo`, `github` (scope distilled memories) → `{session_id, agent}` |
| `memory_session_append` | `session_id`, `role`, `content` → `{turn_count}` |
| `memory_session_close` | `session_id`, `distill=true` (default) queues distillation to durable memory |

### `memory_episodes_list`

Browse the episodic timeline (distilled sessions and logged events).

| Param | Use |
|---|---|
| `topic` | Substring match |
| `since` / `until` | Time bounds on `created_at` |
| `limit` | 1–200 (default 20) |
| `agent` | Optional filter to one agent's episodes |

Default: all agents' episodes (shared brain).

### `memory_procedure_get` / `memory_procedure_set` / `memory_procedures_list`

Versioned playbooks in Postgres (markdown steps agents read and follow).

| Tool | When |
|---|---|
| `memory_procedure_get` | Fetch by `name`, optional `version` (latest if omitted) |
| `memory_procedure_set` | Store new version: `name`, `steps_md`, optional `description`, `tool_recipe`, `tags` |
| `memory_procedures_list` | Discover playbooks; optional `tag`, `limit` |

Each `memory_procedure_set` call creates a new version — use stable names
(e.g. `ship-pr`, `debug-flaky-test`).

### `memory_strategic_*`

Org-wide vision, mission, purpose, and OKR cycles. **Never** use
`memory_remember` for strategic content — use these tools instead.

| Tool | When |
|---|---|
| `memory_strategic_statement_get` | Active vision, mission, or purpose |
| `memory_strategic_statement_set` | Propose a new statement version |
| `memory_strategic_plan_list` / `memory_strategic_plan_get` | Browse OKR cycles |
| `memory_strategic_plan_set` | Propose a new cycle |
| `memory_strategic_objective_set` | Propose an objective |
| `memory_strategic_key_result_set` | Propose a key result |
| `memory_strategic_initiative_set` | Propose an initiative |

All strategic writes return `pending_approval` until a human approves them
in the console (`/app/approvals`).

### `memory_graph_relate` / `memory_graph_related`

Explicit entity relationships (Neo4j when enabled; otherwise no-op with
`reason: graph_disabled`).

| Tool | Use |
|---|---|
| `memory_graph_relate` | `subject`, `predicate`, `object`, optional `weight`, optional `agent` |
| `memory_graph_related` | Expand neighbors of `name`, `depth` (1–4), `limit` |

Use for structured facts vector recall would obscure (e.g. `alice` → `works_on` → `teamshared`).

### `memory_state_get` / `memory_state_set`

Token+repo scoped JSON blobs for client bookkeeping (not durable team knowledge).

| Param | Use |
|---|---|
| `repo` | Workspace slug: absolute path, leading `/` removed, `/` → `-` |
| `key` | Opaque key, e.g. `continual-learning/index` |
| `value` | JSON object (`memory_state_set` only) |

Prefer server state over git for incremental indexes and cadence files when MCP
is available; fall back to `~/.cursor/hooks/state/...` locally.

### `memory_forget`

Soft-delete a semantic/episodic memory by `memory_id` (from a prior recall).
Requires `reason` for audit. **Only when the user explicitly asks.**

## Quick chooser

| Need | Tool |
|---|---|
| Is the server healthy? | `health` |
| Search all memory | `memory_recall` |
| Store preference/fact/event/note | `memory_remember` |
| Multi-turn buffer + distillation | `memory_session_*` |
| Browse timeline | `memory_episodes_list` |
| Versioned how-to | `memory_procedure_set` / `memory_procedure_get` |
| List playbooks | `memory_procedures_list` |
| Vision / OKRs / mission | `memory_strategic_*` or `scope=["strategic"]` |
| Structured relationships | `memory_graph_*` |
| Client incremental state | `memory_state_get` / `memory_state_set` |
| Remove a bad memory | `memory_forget` (user-requested only) |

## Never

- Don't call `memory_forget` without explicit user instruction.
- Don't echo raw memory IDs unless the user asks.
- Don't fabricate hits — if `memory_recall` is empty, say so.
- Don't store secrets, tokens, or credentials in any memory tool.