docs: add memory and models section

content/docs/familiars/index.mdx

@@ -8,3 +8,5 @@ import { HubCards } from '@/components/hub-cards';
 The runtime primitives that own a familiar's state, attach to harnesses, and route work between channels.
 
 <HubCards href="/docs/familiars" />
+
+For continuity and provider boundaries, see [Memory + Models](/docs/memory-models/memory).

content/docs/memory-models/anthropic.mdx

@@ -0,0 +1,31 @@
+---
+title: "Anthropic"
+summary: "Anthropic model access currently flows through the Claude Code harness, not the Coven daemon."
+description: "Anthropic model access in Coven through Claude Code, including setup, doctor checks, and credential boundary."
+read_when:
+  - Connecting Claude Code-backed work to Coven
+  - Debugging Claude auth failures under Coven
+---
+
+# Anthropic
+
+Anthropic model access currently flows through Claude Code.
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude doctor
+coven doctor
+coven run claude "polish this UI"
+```
+
+## Boundary
+
+Claude Code owns Anthropic provider credentials and model calls. Coven owns the session record, PTY supervision, attach/replay behavior, and event log.
+
+Coven does not read Anthropic API keys, OAuth state, or Claude Code credential stores. If Claude Code setup is incomplete, run `claude doctor` and retry.
+
+## Related
+
+- [Claude Code harness](/docs/harnesses/claude-code)
+- [Provider boundary](/docs/memory-models/provider-boundary)
+- [Models](/docs/memory-models/models)

content/docs/memory-models/episodic-memory.mdx

@@ -0,0 +1,31 @@
+---
+title: "Episodic Memory"
+summary: "Episodic memory records specific events, sessions, decisions, outcomes, and evidence."
+description: "Episodic memory for OpenCoven familiars: remembering concrete past work without flattening it into generic facts."
+read_when:
+  - Recording what happened in a session
+  - Looking for previous decisions, merges, releases, or incidents
+---
+
+# Episodic Memory
+
+Episodic memory remembers specific events. It answers "what happened?" and "when did we decide that?"
+
+## Examples
+
+- A docs PR merged and production deployed.
+- A daemon issue was traced to stale socket metadata.
+- A release failed because a provider token expired.
+- A design decision was made after comparing alternatives.
+
+## Relationship to the event log
+
+The session ledger and event log are the raw evidence. Episodic memory is the human-sized summary: enough detail to recover the story, with links or ids back to the source when useful.
+
+Do not replace evidence with vibes. A good episodic note names concrete dates, PRs, commits, commands, or symptoms when they matter.
+
+## Promotion
+
+Episodic memory can later become persistent memory when the lesson is durable. For example, "PR #6 deployed" is episodic; "docs PRs need red/green guards before merge" may become persistent process memory.
+
+See [Memory search](/docs/memory-models/memory-search) for recall patterns.

content/docs/memory-models/index.mdx

@@ -0,0 +1,45 @@
+---
+title: "Memory + Models"
+summary: "How persistent familiars remember across sessions and reach model providers without making Coven a credential gateway."
+description: "Overview of Coven memory layers, memory search, model access, provider boundaries, and current OpenAI/Anthropic/local model posture."
+read_when:
+  - Designing continuity for a familiar
+  - Auditing whether Coven stores model credentials
+---
+
+import { Mermaid } from '@/components/mermaid';
+
+# Memory + Models
+
+Memory is what turns a one-off harness session into a persistent familiar. Models are the provider side of that familiar's reasoning, but Coven does not become a model gateway. The durable runtime boundary is: Coven records sessions and events; clients/familiars derive memory from those events; harnesses own provider auth and model access.
+
+<Mermaid chart={`
+flowchart LR
+  Session[Coven session] --> Ledger[(session ledger + event log)]
+  Ledger --> Memory[Memory layer]
+  Memory --> Working[Working memory]
+  Memory --> Persistent[Persistent memory]
+  Memory --> Episodic[Episodic memory]
+  Memory --> Semantic[Semantic memory]
+  Familiar[Familiar] --> Memory
+  Familiar --> Harness[Harness]
+  Harness --> Provider[Model provider]
+`} />
+
+## Section map
+
+- [Memory overview](/docs/memory-models/memory) defines the four memory layers.
+- [Working memory](/docs/memory-models/working-memory) covers in-session context.
+- [Persistent memory](/docs/memory-models/persistent-memory) covers durable facts and identity.
+- [Episodic memory](/docs/memory-models/episodic-memory) covers specific sessions, decisions, and outcomes.
+- [Semantic memory](/docs/memory-models/semantic-memory) covers embeddings and meaning-based recall.
+- [Memory search](/docs/memory-models/memory-search) covers keyword and semantic lookup.
+- [Models](/docs/memory-models/models) explains why Coven is not a model gateway.
+- [Provider boundary](/docs/memory-models/provider-boundary) names the credential boundary.
+- [OpenAI](/docs/memory-models/openai), [Anthropic](/docs/memory-models/anthropic), and [Local models](/docs/memory-models/local-models) cover provider-specific paths.
+
+## Related
+
+- [Session lifecycle](/docs/familiars/sessions)
+- [Harness provider auth](/docs/harnesses/provider-auth)
+- [Authentication and local access](/docs/reference/auth)

content/docs/memory-models/local-models.mdx

@@ -0,0 +1,33 @@
+---
+title: "Local Models"
+summary: "Local models are a future harness direction, not a daemon-owned provider shortcut."
+description: "How local models should fit Coven through harnesses that talk to local runtimes such as Ollama or llama.cpp."
+read_when:
+  - Planning offline or local-model support
+  - Deciding whether Coven should talk directly to a local model server
+---
+
+# Local Models
+
+Local models are a natural fit for Coven, but they should still arrive through the harness boundary.
+
+Examples of future local-model paths:
+
+- A harness CLI that talks to Ollama.
+- A harness CLI that talks to llama.cpp.
+- A custom adapter that runs a local model-backed agent process.
+
+## Current posture
+
+Local models are not a special daemon credential feature. The daemon should not grow provider-specific model routing just because the provider is local.
+
+The same rules apply:
+
+- Stable harness id.
+- Fixed adapter command shape.
+- Project-root and working-directory validation.
+- PTY supervision.
+- Session ledger and event log.
+- No secret fields in the socket API.
+
+For adapter requirements, see [Custom adapters](/docs/harnesses/custom-adapters) and [Models](/docs/memory-models/models).

content/docs/memory-models/memory-search.mdx

@@ -0,0 +1,35 @@
+---
+title: "Memory Search"
+summary: "Memory search combines keyword, semantic, and scoped recall without exposing unrestricted private history."
+description: "How familiars and clients should search working, persistent, episodic, and semantic memory safely."
+read_when:
+  - Designing a familiar recall feature
+  - Debugging why memory search returned too much or too little
+---
+
+# Memory Search
+
+Memory search is how a familiar finds relevant prior context. It should be scoped, attributable, and small enough to read.
+
+## Search modes
+
+| Mode | Good for |
+| --- | --- |
+| Keyword search | Exact filenames, commands, PR numbers, names, error strings. |
+| Semantic search | Similar ideas, architecture patterns, repeated lessons. |
+| Timeline search | Recent events and session chronology. |
+| Manual pinned memory | Hard rules and durable preferences. |
+
+## Safety rules
+
+- Search only the memory scope the current surface is allowed to see.
+- Return summaries with source references where possible.
+- Prefer a few high-signal results over a large dump.
+- Do not use search as permission to reveal private memory in shared contexts.
+- Treat search hits as leads; read the source before acting.
+
+## Relationship to sessions
+
+The session ledger and event log are useful evidence sources, but not every event should enter memory search. Clients should index curated notes, summaries, and selected event text according to the familiar's privacy and retention rules.
+
+See [Episodic memory](/docs/memory-models/episodic-memory) and [Semantic memory](/docs/memory-models/semantic-memory).

content/docs/memory-models/memory.mdx

@@ -0,0 +1,41 @@
+---
+title: "Memory"
+summary: "The four-layer memory model for persistent familiars: working, persistent, episodic, and semantic."
+description: "Memory overview for OpenCoven familiars and how memory relates to Coven sessions, event logs, and client-owned recall."
+read_when:
+  - You need to explain how familiars remember
+  - You are choosing which memory layer a feature should write to
+---
+
+# Memory
+
+Coven's daemon records what happened. A familiar's memory layer decides what should be remembered, summarized, searched, and loaded into future sessions.
+
+The daemon does not enforce one memory backend. It gives clients a durable session ledger and event log. Familiar layers can build working, persistent, episodic, and semantic memory on top.
+
+## Four memory layers
+
+| Layer | Scope | Examples |
+| --- | --- | --- |
+| Working memory | One active session or task | Current goal, active files, constraints, recent turns. |
+| Persistent memory | Cross-session durable facts | User preferences, familiar identity, project conventions. |
+| Episodic memory | Specific events and outcomes | PR #6 merged, release succeeded, incident root cause found. |
+| Semantic memory | Meaning-based recall | Similar past debugging patterns, docs topics, architecture concepts. |
+
+## What the daemon provides
+
+The daemon provides:
+
+- Session records.
+- Append-only events.
+- Project-rooted harness context.
+- Attach and replay behavior.
+- Local socket access for clients.
+
+Memory lives above that. A client can summarize a session into persistent memory, index event text into semantic memory, or load selected memories back into a familiar prompt.
+
+## Related
+
+- [Session lifecycle](/docs/familiars/sessions)
+- [Memory search](/docs/memory-models/memory-search)
+- [Familiars](/docs/familiars/sessions)

content/docs/memory-models/meta.json

@@ -0,0 +1,20 @@
+{
+  "title": "Memory + Models",
+  "description": "Memory layers, search, provider boundaries, and model access for persistent familiars.",
+  "root": true,
+  "icon": "LuBrainCircuit",
+  "pages": [
+    "index",
+    "memory",
+    "working-memory",
+    "persistent-memory",
+    "episodic-memory",
+    "semantic-memory",
+    "memory-search",
+    "models",
+    "provider-boundary",
+    "openai",
+    "anthropic",
+    "local-models"
+  ]
+}

content/docs/memory-models/models.mdx

@@ -0,0 +1,31 @@
+---
+title: "Models"
+summary: "Coven is not a model gateway. Harnesses own model provider access."
+description: "Model access overview for Coven: OpenAI through Codex, Anthropic through Claude Code, local models through future harnesses, and no daemon credential ownership."
+read_when:
+  - Auditing where model calls happen
+  - Deciding how a familiar should reach a provider
+---
+
+# Models
+
+Coven is not a model gateway. It does not store provider credentials, route model API calls, or mint provider tokens. A familiar reaches models through a harness.
+
+## Current model paths
+
+| Provider path | Current posture |
+| --- | --- |
+| OpenAI | Through the [Codex harness](/docs/harnesses/codex). |
+| Anthropic | Through the [Claude Code harness](/docs/harnesses/claude-code). |
+| Google | Future adapter direction; not current v0 support. |
+| Local models | Future/local harness direction; not a daemon credential feature. |
+
+## What Coven sees
+
+Coven sees harness process output and exits. It does not see provider API requests unless the harness prints them. It does not need API keys to launch a session.
+
+## Client rule
+
+Clients should not pass model credentials into Coven. They should launch a harness whose provider auth is already complete and let the harness call the provider.
+
+For the exact credential boundary, see [Provider boundary](/docs/memory-models/provider-boundary) and [Harness provider auth](/docs/harnesses/provider-auth).

content/docs/memory-models/openai.mdx

@@ -0,0 +1,31 @@
+---
+title: "OpenAI"
+summary: "OpenAI model access currently flows through the Codex harness, not the Coven daemon."
+description: "OpenAI model access in Coven through Codex, including login, doctor checks, and credential boundary."
+read_when:
+  - Connecting OpenAI-backed work to Coven
+  - Debugging Codex auth failures under Coven
+---
+
+# OpenAI
+
+OpenAI model access currently flows through Codex.
+
+```bash
+npm install -g @openai/codex
+codex login
+coven doctor
+coven run codex "fix the failing tests"
+```
+
+## Boundary
+
+Codex owns OpenAI provider credentials and model calls. Coven owns the session record, PTY supervision, attach/replay behavior, and event log.
+
+Coven does not read OpenAI API keys, OAuth refresh tokens, or Codex auth files. If Codex auth expires, run `codex login` and retry.
+
+## Related
+
+- [Codex harness](/docs/harnesses/codex)
+- [Provider boundary](/docs/memory-models/provider-boundary)
+- [Models](/docs/memory-models/models)

content/docs/memory-models/persistent-memory.mdx

@@ -0,0 +1,34 @@
+---
+title: "Persistent Memory"
+summary: "Persistent memory stores stable facts that should survive sessions, daemon restarts, and context resets."
+description: "Persistent memory for familiar identity, user preferences, project conventions, and long-term operating rules."
+read_when:
+  - Capturing durable facts for a familiar
+  - Reviewing whether a memory should survive future sessions
+---
+
+# Persistent Memory
+
+Persistent memory is for stable facts that should survive context resets and daemon restarts. It is the layer that gives a familiar continuity.
+
+## Good persistent memories
+
+- Familiar identity and role.
+- User preferences and communication style.
+- Project conventions and hard rules.
+- Stable infrastructure notes.
+- Repeated lessons from prior incidents.
+
+## Poor persistent memories
+
+- Raw command output.
+- One-off failed hypotheses.
+- Secrets, tokens, or private URLs.
+- Temporary task state.
+- Facts that are likely to expire quickly.
+
+## Promotion rule
+
+Promote memory deliberately. A good persistent memory should still be useful weeks later and should not expose private material in the wrong context.
+
+For concrete sessions and outcomes, use [Episodic memory](/docs/memory-models/episodic-memory). For concept-based recall, use [Semantic memory](/docs/memory-models/semantic-memory).