# https://github.com/phasespace-labs/palinode Project Manual

Generated at: 2026-06-25 01:42:56 UTC

## Table of Contents

- [Overview, Supported Platforms, and Quickstart](#page-overview)
- [System Architecture and Interface Layer](#page-architecture)
- [Indexing, Search, LLM Compaction, and Audit](#page-memory-ai)
- [Deployment, Diagnostics, Obsidian, and Extensibility](#page-ops)

<a id='page-overview'></a>

## Overview, Supported Platforms, and Quickstart

### Related Pages

Related topics: [System Architecture and Interface Layer](#page-architecture), [Deployment, Diagnostics, Obsidian, and Extensibility](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)
- [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)
- [claude-plugin/.claude-plugin/plugin.json](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/.claude-plugin/plugin.json)
- [claude-plugin/.mcp.json](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/.mcp.json)
- [examples/CLAUDE.md](https://github.com/phasespace-labs/palinode/blob/main/examples/CLAUDE.md)
- [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py)
- [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)
- [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)
- [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)
- [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)
</details>

# Overview, Supported Platforms, and Quickstart

## Purpose and Scope

Palinode is an agent memory layer that stores knowledge as plain Markdown files with YAML frontmatter under a git repo you control. The system is "local-first" — there are no accounts, no cloud dependency, and no vendor lock-in. Memory is consumable across multiple IDEs and agent runtimes via the Model Context Protocol (MCP), and every write produces a reviewable git commit ([README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)).

The project's core principles, as stated in the README, are:

1. **Your data, your files** — markdown files in a directory you own; export is `cp`; backup is `git push`.
2. **Cross-IDE memory** — one memory store, many MCP-compatible editors.
3. **Git operations as agent tools** — `diff`, `blame`, `rollback`, `push` exposed via MCP.
4. **Operation-based compaction** — KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE operations, each producing a deterministic git commit.
5. **Per-fact addressability** — invisible `<!-- fact:slug -->` IDs inline in markdown, targetable by compaction.
6. **4-phase injection** — Core + Topic + Associative + Triggered context windows.
7. **Multi-transport MCP** — stdio for local editors, Streamable HTTP for remote ([README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)).

## High-Level Architecture

The Palinode runtime consists of three cooperating processes: the FastAPI HTTP server, the stdio MCP bridge, and the on-disk Markdown store fronted by SQLite-vec + FTS5 indexes. The HTTP server exposes REST endpoints, the MCP bridge talks to MCP-compatible agents, and the watcher auto-embeds new files into the index.

```mermaid
flowchart LR
    A[Agent / IDE<br/>Claude Code, Cursor, Zed, VS Code] -->|MCP stdio| B[palinode-mcp]
    A -->|MCP HTTP| C[palinode-api<br/>FastAPI :6340]
    B -->|REST| C
    C --> D[(Memory Store<br/>Markdown + git)]
    C --> E[(SQLite-vec<br/>Vector index)]
    C --> F[(SQLite FTS5<br/>Keyword index)]
    C --> G[Ollama<br/>BGE-M3 embeddings]
    H[palinode CLI] -->|REST| C
```

Source: [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py), [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)

## Supported Platforms and Integrations

### MCP-Compatible Editors

Palinode presents itself as an MCP server. The Claude Code plugin scaffold (`claude-plugin/`) is the canonical local integration; it ships a plugin manifest and an MCP server definition ([claude-plugin/.claude-plugin/plugin.json](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/.claude-plugin/plugin.json), [claude-plugin/.mcp.json](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/.mcp.json)). The community is actively working through coverage of other editors; issue #24 ("Multi-platform MCP and integration docs") tracks Claude Code, Cursor, Zed, and VS Code setup instructions, and issue #60 covers OpenClaw and Hermes-agent. The README itself already lists Claude Code, Cursor, Windsurf, and Zed as supported targets ([README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)).

### MCP Transports

| Transport | Use case | Endpoint |
|-----------|----------|----------|
| stdio | Local editor on the same machine | `palinode-mcp` |
| Streamable HTTP | Remote editor or LAN agent | `http://localhost:6340/mcp` |
| REST | CLI and external scripts | `http://localhost:6340/*` |

Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md), [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py)

### Distribution Channels

In addition to `pip install`, Palinode is distributed via a Homebrew tap (`brew install palinode`, tracked in issue #8), a Nix flake with a systemd module (issue #7, shipped), and is queued for submission to community MCP directories — the Official MCP Registry, Smithery, mcp.so, and Cline (issue #35). Submission to the Anthropic Connectors Directory is gated on the MCPB bundle shipping (issues #29 and #62).

## Quickstart

The canonical zero-friction path is summarized in `examples/CLAUDE.md` ([examples/CLAUDE.md](https://github.com/phasespace-labs/palinode/blob/main/examples/CLAUDE.md)) and tracked as the "CLAUDE.md integration — zero-friction adoption path" effort in issue #32.

### 1. Install and Initialize

```bash
# Install (one of):
pip install palinode        # PyPI
brew install palinode       # Homebrew tap (issue #8)
nix profile install .       # Nix flake (issue #7)

# Scaffold the memory directory:
palinode init --obsidian ~/Documents/palinode-memory
```

`palinode init` creates the canonical directory layout: `people/`, `projects/`, `decisions/`, `insights/`, `research/`, `archive/`, and the managed `.palinode/` index state ([palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)). The init command is idempotent — re-running it restores scaffolded files without clobbering user edits.

### 2. Start the Server

```bash
palinode-api                # FastAPI on http://localhost:6340
```

Verify reachability:

```bash
curl http://localhost:6340/status
# expect: { "ollama_reachable": true, ... }
```

Source: [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md), [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py)

### 3. Wire Up Your Agent

For Claude Code, the plugin scaffold provides the wiring out of the box. For other MCP clients, point them at the stdio binary `palinode-mcp` or the HTTP endpoint `http://localhost:6340/mcp`. The bundled troubleshooting section in `claude-plugin/README.md` notes three common failures: missing `palinode-mcp` on PATH (re-run `pip install -e .`), API connection refused (start `palinode-api`), and embedder connection refused (start Ollama) ([claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)).

### 4. Save, Search, and Backfill

Save from any agent via the `palinode_save` MCP tool or the `POST /save` REST endpoint; the write layer auto-emits a git commit and injects an idempotent `## See also` wiki footer for un-linked entities ([palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)). Search with `palinode_search`; lint with `palinode_lint`. The `palinode obsidian-sync` CLI walks legacy memory files and backfills the wiki footer introduced after Deliverable C — dry-run by default, pass `--apply` to write ([palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)).

### 5. Optional: AI Bootstrap Helpers

Issue #61 tracks an `llms-install.md` file that gives agents a step-by-step bootstrap recipe (Ollama detection, venv-path discipline) to remove the two recurring friction points observed during Cline preflight testing on 2026-04-29. Until that file ships, the README and `examples/CLAUDE.md` are the canonical bootstrap entry points.

## Common Failure Modes

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `palinode-mcp: command not found` | Console script not on PATH | Re-run `pip install -e .` from source |
| `Failed to connect to Palinode API` | HTTP server not running | Start `palinode-api`; verify with `curl /status` |
| `Embedder error: connection refused` | Ollama not running | `ollama serve` or start the macOS app |
| Search returns nothing | Watcher hasn't indexed yet | Check `total_files` / `fts_chunks` in `/status` |

Source: [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md), [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)

## See Also

- [Memory Model and Frontmatter Schema](memory-model.md)
- [Compaction DSL: KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE](compaction-dsl.md)
- [MCP Tools Reference](mcp-tools.md)
- [Embedding, Indexing, and the Watcher](indexing-watcher.md)

---

<a id='page-architecture'></a>

## System Architecture and Interface Layer

### Related Pages

Related topics: [Overview, Supported Platforms, and Quickstart](#page-overview), [Indexing, Search, LLM Compaction, and Audit](#page-memory-ai), [Deployment, Diagnostics, Obsidian, and Extensibility](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)
- [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py)
- [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py)
- [palinode/api/_util.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/_util.py)
- [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)
- [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py)
- [palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py)
- [palinode/api/ui/templates/fact.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/fact.html)
- [palinode/api/ui/templates/diffs.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/diffs.html)
- [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html)
- [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)
- [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)
- [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)
</details>

# System Architecture and Interface Layer

## Overview

Palinode exposes a single underlying memory store (markdown files in a git repo, indexed by SQLite-vec + FTS5) through three convergent interfaces and a human-facing web UI. Every tool — `save`, `search`, `blame`, `rollback`, `consolidate`, `lint`, etc. — is reachable as `palinode_<name>` via MCP, `palinode <name>` via the CLI, `POST/GET /<name>` via the REST API, and as a server-rendered page in the dashboard. This "one server, four surfaces" design is what lets the same memory back Claude Code, Cursor, Zed, and Cline simultaneously ([README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)).

The interface layer is split into `palinode.api.routers/` (split router packages for MCP/REST), `palinode.api.ui/` (Jinja templates + sanitized markdown rendering), and `palinode.cli/` (Click commands). v0.8.15 explicitly added `palinode.api.routers` to the wheel packaging list because v0.8.14's split source tree shipped a broken `palinode` console command that couldn't import the server module — a regression test now guards the package set ([README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)).

```mermaid
flowchart LR
    subgraph Clients
        IDE[Claude Code / Cursor / Zed / Cline]
        CLI[CLI - palinode ...]
        UI[Web Browser Dashboard]
    end
    subgraph Transports
        STDIO[stdio MCP]
        HTTP[Streamable HTTP / REST]
        Web[FastAPI Jinja]
    end
    subgraph palinode.api
        Routers[routers/ - memory, search, ...]
        MemWrite[memory_write]
        Enrich[enrichment]
        Util[_util - sanitized 500, retrieval log]
        UIRender[ui/render.py - nh3 + markdown-it]
    end
    Store[(Markdown + YAML\n+ git\n+ SQLite-vec + FTS5)]
    IDE -->|MCP| STDIO --> Routers
    CLI --> Routers
    UI --> Web --> UIRender
    Routers --> MemWrite
    Routers --> Enrich
    Routers --> Util
    MemWrite --> Store
    Enrich --> Store
```

## The REST / MCP Router Layer

`palinode.api.routers.memory` is the central write path. When a file is written it is parsed, frontmatter is normalized, an auto-description is generated if the file is eligible, and a wikilink footer (`## See also`) is injected for any entity not already linked inline ([palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py)). Eligibility for the persisted `description` field is decided by `_is_description_eligible`, which checks that the file lives directly under one of the memory-category directories; `daily/`, `archive/`, `specs/`, and top-level docs are excluded so the watcher does not burn inference on output it would throw away ([palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)).

Cross-cutting plumbing — sanitized 500 helpers, the UTC clock, CWD→slug derivation, and the retrieval-event logger — lives in `palinode/api/_util.py`. This module was extracted from the former `routers/_shared.py` "junk drawer" so that genuinely miscellaneous helpers don't pollute any one themed router module ([palinode/api/_util.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/_util.py)).

The enrichment subsystem (`palinode/api/enrichment.py`) wraps a one-line description prompt around memory content and routes through a centralized chat client with a primary/fallback chain. On `OllamaError`, `OllamaTimeout`, or `OllamaCircuitOpen` the call returns an empty string and the watcher retries on the next pass rather than blocking the write path inline ([palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py)).

## The Web UI Layer

The dashboard is served from `palinode/api/ui/` and renders Jinja templates that are intentionally store-agnostic. Markdown bodies are rendered with `markdown-it-py` (HTML disabled) and then run through `nh3` (an `ammonia`/`html5lib` sanitizer) as a defense-in-depth backstop. The allow-list covers prose, headings, lists, code, tables, and links — but explicitly omits `<script>`, `<style>`, `<iframe>`, `<object>`, `<form>`, and any event-handler-bearing element, because the body is agent-generated and raw HTML in markdown is an XSS vector ([palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py)).

The three template surfaces most often reached from a CLI / MCP session-end flow are:

| Template | Purpose | Source |
|----------|---------|--------|
| `fact.html` | Single memory view with provenance chip and tamper-detection pill | [fact.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/fact.html) |
| `diffs.html` | Recent git commits grouped by day with file pills linking back to `fact` | [diffs.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/diffs.html) |
| `quality.html` | Lint-driven quality queues (orphans, contradictions, staleness) | [quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html) |

The `fact.html` template renders a provenance aside that flips to a `broken-seal` style when `broken_seal` is set, which is how the UI surfaces tamper detection back to the operator without exposing raw commit hashes ([palinode/api/ui/templates/fact.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/fact.html)).

## The CLI Layer

The CLI is a thin Click wrapper that delegates to the same router functions the MCP and REST surfaces use. `palinode init` scaffolds the canonical directory tree (`people/`, `projects/`, `decisions/`, `insights/`, `research/`, `archive/`, `.palinode/`) and explicitly notes that wikilinks (`[[like this]]`) are first-class — Palinode reads and writes them, and that `.palinode/` is daemon-managed and must not be edited ([palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)).

`palinode obsidian-sync` is a one-shot backfill that walks the memory directory and applies the same `_apply_wiki_footer` transformation the live write path uses. By default it is a dry run; `--apply` writes changes, `--include` and `--exclude` scope the walk, and the skip set mirrors `lint.py` plus Obsidian's `.obsidian/` config dir. Already-synced files are silently skipped so re-runs are idempotent ([palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)).

The `palinode orphan-repair` Click command shells out to the API's `orphan_repair` tool, which returns semantically related files for a broken `[[wikilink]]` target so the operator can either redirect the link or create the missing target with informed context ([palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)). Together these CLI commands implement the "zero taxonomy burden" principle called out in the README: the system classifies, the human reviews, and the data stays as plain markdown that any tool — including `cat` — can read.

## See Also

- [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) — high-level overview, stack, and tool inventory
- Community tracking: issue #24 (multi-platform MCP install docs for Claude Code, Cursor, Zed, VS Code), issue #29 / #62 (Anthropic Connectors Directory submission prerequisites), issue #61 (`llms-install.md` for agent-bootstrap friction), and issue #32 (zero-friction `CLAUDE.md` adoption) — all directly shape how the interface layer is documented and packaged.

---

<a id='page-memory-ai'></a>

## Indexing, Search, LLM Compaction, and Audit

### Related Pages

Related topics: [System Architecture and Interface Layer](#page-architecture), [Deployment, Diagnostics, Obsidian, and Extensibility](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)
- [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py)
- [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py)
- [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)
- [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py)
- [palinode/api/ui/router.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/router.py)
- [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html)
- [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)
- [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)
- [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)
- [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)
</details>

# Indexing, Search, LLM Compaction, and Audit

## Overview

Palinode treats markdown files in a single directory as the source of truth for an agent's long-term memory. Four cooperating subsystems keep that corpus queryable, summarizable, and accountable:

- **Indexing** watches the memory directory, parses frontmatter, embeds chunks into a vector index, and writes auto-generated descriptions and summaries.
- **Search** combines SQLite-vec cosine similarity with SQLite FTS5 BM25 keyword matching, plus ambient project-aware retrieval.
- **LLM Compaction** uses a KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE operation DSL applied deterministically and committed to git.
- **Audit** leverages git provenance — `history`, `blame`, `diff`, and `rollback` — so every fact traces back to the commit that recorded it.

These surfaces are exposed via three transports (MCP `palinode_*`, CLI `palinode <name>`, REST `POST/GET /<name>`) from the same FastAPI process. Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

---

## Indexing Pipeline

### Watcher and Eligibility

The memory router runs a file-watcher pass that re-indexes every markdown file under `memory_dir`. For each file, the router checks two predicates before doing expensive LLM work:

| Step | Predicate / action | Source |
|------|--------------------|--------|
| Description eligible? | First path segment must be in `_MEMORY_CATEGORY_DIRS` (`projects/`, `decisions/`, `insights/`, `research/`, `people/`, etc.); excludes `daily/`, `archive/`, `specs/`, and top-level docs | [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) |
| Description generated? | Only if `metadata.get("description")` is absent | [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) |
| Summary generated? | Only if `metadata.get("core")` is True and `summary` is missing | [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) |

The eligibility predicate prevents the watcher from re-running inference on files whose write-back is a no-op (the permanent-backlog bug fixed in #472). Source: [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py).

### LLM Enrichment

Description and summary generation both route through the centralized Ollama chat client. The prompt is hardened against prompt injection by wrapping user content in `<user_content>` tags and forbidding openers like "The memory" or "This memory". Source: [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py).

`_generate_description` returns a `_DESCRIPTION_DEFERRED` sentinel when Ollama is slow or the circuit breaker is open — the watcher counts that as a transient error and retries on the next pass instead of burning inference budget on a doomed call. Source: [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py).

### Wiki-Contract Auto-Footer

When a memory file has an `entities:` frontmatter list but no inline `[[wikilinks]]` for those slugs, `_apply_wiki_footer` appends a detectable `## See also` block so Obsidian graph view picks up the relationship. The footer is idempotent — re-saving replaces or strips it — and validates every slug against `_SAFE_SLUG_RE` (`^[A-Za-z0-9._-]+$`) to prevent entity-list injection of markdown structure. Source: [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py).

Legacy files written before the auto-footer shipped can be backfilled with `palinode obsidian-sync` (dry-run by default, `--apply` to write). Source: [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py).

---

## Search

### Hybrid Retrieval

Palinode's search layer is hybrid by design:

- **Vector index** — SQLite-vec embedded; embeddings produced by BGE-M3 via Ollama, no API key, fully local.
- **Keyword index** — SQLite FTS5 embedded; BM25 for exact-term queries with zero dependencies.

Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

### Ambient Context Search (ADR-008)

A recurring community pain point (issue #28): when many memory files exist across multiple projects, a search for "ADR-004" from a Palinode working directory returned results from unrelated projects instead of project-specific memory. The fix — ambient context search — automatically weights results toward files under the current project's working directory. This is the active design thread behind `palinode_search` results that "just know" which repo you are in.

### Embedding-Tool Commands

The `embedding_tools` CLI mirrors the MCP API for maintenance passes:

| Command | Purpose | Source |
|---------|---------|--------|
| `palinode dedup-suggest` | Flag near-duplicates of a draft before save; strong dup threshold ≥0.90 | [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) |
| `palinode orphan-repair` | Given a broken `[[wikilink]]`, return files semantically near the target | [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) |
| `palinode cluster-neighbors` | Files semantically related but NOT yet wiki-linked — surfaces implicit cross-link candidates | [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) |
| `palinode topic-coverage` | Returns `covered` / `best_match` / `similarity` for whether any page already covers a topic phrase | [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) |

All commands honor TTY-aware output (text for humans, JSON when piped). Source: [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py).

---

## LLM Compaction

Compaction is the operation that prevents unbounded memory growth. The agent does not edit files directly — it proposes a list of structured operations that a deterministic executor applies:

| Operation | Effect |
|-----------|--------|
| `KEEP` | Leave the chunk untouched |
| `UPDATE` | Rewrite content in place |
| `MERGE` | Combine two or more chunks into one |
| `SUPERSEDE` | Mark old chunk as replaced; preserve for audit |
| `ARCHIVE` | Move chunk to `archive/` |

The vocabulary maps cleanly onto the IETF Knowledge Unit draft lifecycle (community discussion #17). Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

The executor commits the resulting change to git so every compaction is reviewable. A `-history.md` consolidation-audit sibling is written next to the changed file; the UI router enumerates these for the audit page. Source: [palinode/api/ui/router.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/router.py).

`palinode consolidate` is exposed in two modes: preview (dry-run the proposed operations) and apply (commit). Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

---

## Audit & Provenance

Because the memory directory is a git repository, every write — save, compaction, session-end — produces a commit. That gives Palinode four audit primitives that no other memory layer exposes:

| Tool | Returns | Source |
|------|---------|--------|
| `palinode_diff` | What changed in the last N days | [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) |
| `palinode_blame` | Commit that recorded a given line or `<!-- fact:slug -->` | [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) |
| `palinode_history` | Git history for a file with diff stats and rename tracking (supersedes the deprecated `palinode_timeline`) | [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) |
| `palinode_rollback` | Revert a file to a previous commit; safe — creates a new commit rather than rewriting history | [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) |

The "Build in public" community thread (#33) demonstrates the model in practice: a real compaction diff shown with `git blame` proving provenance. The pending `claim_id` layer on `palinode_blame` (#65) addresses the epistemic-integrity concern raised in the Karpathy gist thread — distinguishing *when-written* from *what-justifies* a claim. Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

The web UI surfaces a `/quality` page that lists contradictions, orphans, and stale files detected by `palinode_lint`, each linking to the offending fact. Source: [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html).

```mermaid
flowchart LR
  A[Memory .md file] --> B[Watcher]
  B --> C{Eligible?}
  C -- no --> Z[skip]
  C -- yes --> D[Ollama Embed BGE-M3]
  D --> E[(SQLite-vec)]
  D --> F[(SQLite FTS5)]
  B --> G[_generate_description]
  B --> H[_generate_summary]
  G --> I[Inject into frontmatter]
  H --> I
  I --> J[git commit]
  J --> K[Audit: blame / diff / history]
  E --> L[Search: hybrid]
  F --> L
  L --> M[Agent context / 4-phase injection]
```

---

## Common Failure Modes

| Symptom | Likely cause | First check |
|---------|--------------|-------------|
| Search returns nothing | Watcher hasn't indexed yet | `palinode_status` — check `total_files` and `fts_chunks` ([claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)) |
| "Embedder error: connection refused" | Ollama not running | `ollama serve` or restart the macOS app ([claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)) |
| `ollama_reachable: false` from `/status` | API can't reach Ollama on `localhost:11434` | Verify Ollama daemon ([claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)) |
| Description never written | File is in `daily/`, `archive/`, `specs/`, or top-level — outside `_MEMORY_CATEGORY_DIRS` ([palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)) |
| `description deferred` errors in watcher logs | Ollama slow / circuit-open — transient; next pass retries ([palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py)) |
| `palinode-mcp: command not found` | MCP binary not on PATH | Re-run `pip install -e .` from the source dir ([claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)) |

---

## See Also

- `palinode init` — scaffolds the memory directory and category tree ([palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py))
- `palinode obsidian-sync` — backfills the wiki-contract auto-footer to legacy files ([palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py))
- Multi-platform MCP install (Claude Code, Cursor, Zed, VS Code) — tracked in issue #24
- Anthropic Connectors Directory submission — deferred until the MCPB bundle ships (issue #62)

---

<a id='page-ops'></a>

## Deployment, Diagnostics, Obsidian, and Extensibility

### Related Pages

Related topics: [Overview, Supported Platforms, and Quickstart](#page-overview), [System Architecture and Interface Layer](#page-architecture), [Indexing, Search, LLM Compaction, and Audit](#page-memory-ai)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)
- [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)
- [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)
- [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)
- [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py)
- [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py)
- [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py)
- [palinode/api/_util.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/_util.py)
- [palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py)
- [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html)
- [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)

</details>

# Deployment, Diagnostics, Obsidian, and Extensibility

Palinode ships as a pip-installable Python package with three cooperating processes: `palinode-api` (HTTP on port 6340), `palinode-mcp` (stdio MCP server), and `palinode-watcher` (filesystem indexer). Beyond installation, the project invests heavily in **operational diagnostics**, an **Obsidian-aware wiki contract**, and **extension surfaces** for editors, NixOS, and CI agents. This page maps those concerns to the source files that implement them.

## Deployment and Installation

The canonical install is `pip install -e .` from the repository root, which registers four console scripts: `palinode`, `palinode-api`, `palinode-mcp`, and `palinode-watcher`. A successful install also creates the SQLite-vec + FTS5 store on first run. Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

`palinode init` is the on-ramp for a new project. It scaffolds a complete memory layout — `people/`, `projects/`, `decisions/`, `insights/`, `research/`, `archive/`, and `.palinode/` — plus the editor glue files expected by Claude Code, Cursor, and Obsidian:

| Generated file | Purpose |
|----------------|---------|
| `.claude/CLAUDE.md` | Project-local agent instructions that teach Claude about Palinode commands |
| `.claude/settings.json` | Hook registration (e.g. `palinode-session-end.sh`) |
| `.claude/commands/{save,ps,wrap}.md` | Slash-command bodies (single source of truth — no drift) |
| `.mcp.json` | MCP server registration for stdio transport |
| `.obsidian/{app,graph,workspace}.json` | Wikilinks on, `daily/` as default, color groups |
| `_index.md`, `_README.md` | Starter Map-of-Content and vault orientation |

`--obsidian <vault-path>` writes the Obsidian scaffold; `--force-obsidian` overwrites it while preserving `workspace.json`. Source: [palinode/cli/init.py:1-120](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py).

The Claude Code plugin scaffold (`claude-plugin/`) replaces the older OpenClaw `plugin/` directory that shipped before v0.6.0, reflecting the migration tracked in issue #2. The plugin README documents the same troubleshooting matrix used by the daemon — missing PATH, Ollama unreachable, stale search results. Source: [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md).

## Diagnostics and Observability

`palinode doctor` runs 18+ checks across paths, services, config consistency, index health, and disk state. The output is a structured pass/warn/fail report; `--fix` applies safe automated repairs (creates missing directories, appends the CLAUDE.md Palinode block) but never moves user data — phantom DB files and path mismatches print suggested `mv` commands instead. `palinode doctor_deep` adds a canary write test (~10–15 s). Source: [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md).

Two observability channels are wired into every request path:

1. **Retrieval-event instrumentation (ADR-007 prerequisite, #256).** A lazy-initialised `RetrievalLogger` writes to the memory directory when `config.instrumentation.capture_retrievals` is true. The flag is honoured by the env var `PALINODE_INSTRUMENTATION_DISABLED` for CI runs that need a clean disk. Source: [palinode/api/_util.py:1-40](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/_util.py).
2. **Reindex / auto-summary counters.** The watcher path increments `desc_count`, `desc_errors`, and a "description deferred (ollama slow)" sentinel counter. Deferrals (Ollama circuit-open or timeout) are not failures — they leave the file eligible and the next watcher pass retries. Source: [palinode/api/routers/memory.py:1-60](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py).

Auto-summarization routes through a centralized chat client with retries=0 (latency-sensitive). If the primary returns empty/garbage, the fallback chain runs; if both fail, `_clean_llm_oneliner` extracts the first prose line as a backstop. The eligibility predicate excludes `daily/`, `archive/`, `specs/`, and top-level docs — counting their descriptions was the permanent-backlog bug #472 fixed by the predicate. Source: [palinode/api/enrichment.py:1-80](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py).

The provenance UI renders agent-generated markdown through `markdown-it-py` (HTML disabled) and a second nh3 sanitizer pass. The sanitizer is the load-bearing layer — it strips `<script>`, `onerror=`, and `javascript:` regardless of how they entered the markdown body. Source: [palinode/api/ui/render.py:1-30](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py). The Quality Queues dashboard (`/ui/quality`) surfaces `lint` findings grouped by kind — contradictions get a dedicated presentation row that links back to the fact entity. Source: [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html).

## Obsidian Integration and the Wiki Contract

Wikilinks (`[[like this]]`) are first-class. Every `palinode_save` writes a Layer 2 auto-footer under `## See also` that links any `entities:` frontmatter entry that is not already linked inline. The footer is **idempotent** — entity refs use the slash form `category/slug`, and only the *slug* part becomes the `[[...]]` target. Hostile entity slugs containing `]]`, `|`, whitespace, or other markdown-special characters are dropped via `_safe_wiki_slug` (regex `^[A-Za-z0-9._-]+$`) before emission. Source: [palinode/api/memory_write.py:1-120](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py).

`palinode obsidian-sync` is the backfill CLI for files written before Deliverable C (the auto-footer) shipped. It walks all `.md` files under `PALINODE_DIR`, skipping `archive/`, `logs/`, `.obsidian/`, and `.palinode/`, then applies the same `_apply_wiki_footer` transformation in bulk. Default is a **dry run**; pass `--apply` to write. Idempotent re-runs detect the existing auto-footer marker and skip silently. Include/exclude globs scope the pass:

```bash
palinode obsidian-sync --apply --include "projects/*.md" --exclude "archive/**"
```

Source: [palinode/cli/obsidian_sync.py:1-80](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py).

## Extensibility Surfaces

Four CLI commands form the **Obsidian embedding-tool MVP** (issues #210 and #235). All four honor TTY-aware output (text for humans, JSON when piped) and proxy through the same MCP/API surface:

```mermaid
flowchart LR
    A[Agent / User] -->|CLI| B[palinode dedup-suggest]
    A -->|CLI| C[palinode orphan-repair]
    A -->|CLI| D[palinode cluster-neighbors]
    A -->|CLI| E[palinode topic-coverage]
    B --> F[palinode-api :6340]
    C --> F
    D --> F
    E --> F
    F --> G[(SQLite-vec + FTS5)]
    F --> H[Ollama bge-m3]
```

- **`dedup-suggest`** flags strong duplicates at ≥0.90 similarity for draft content.
- **`orphan-repair`** finds semantic matches for broken `[[wikilinks]]` to either propose redirects or scaffold the missing target file.
- **`cluster-neighbors`** lists files semantically related but NOT already wiki-linked to or from a given file (surfaces implicit cross-link candidates).
- **`topic-coverage`** answers `covered` / `best_match` / `similarity` for a topic phrase — a binary gate before creating new pages.

Source: [palinode/cli/embedding_tools.py:1-80](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py).

Beyond the editor plugin and CLI, the project also exposes a Nix flake plus a NixOS/nix-darwin service module (issue #7, shipped), and tracks Anthropic Connectors Directory submission for after an MCPB bundle ships (#62). The CLAUDE.md integration (#32) and Homebrew tap (#8) are open work that lowers the friction to zero for new adopters.

## See Also

- [Core Architecture and Memory Model](#)
- [MCP Tool Reference](#)
- [Compaction Operations (KEEP / UPDATE / MERGE / SUPERSEDE / ARCHIVE)](#)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: phasespace-labs/palinode

Summary: Found 34 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline)
- User impact: Developers may fail before the first successful local run: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline)
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/61

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Anthropic Connectors Directory submission (after MCPB bundle ships)
- User impact: Developers may fail before the first successful local run: Anthropic Connectors Directory submission (after MCPB bundle ships)
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/62

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Build in public — show Palinode building Palinode
- User impact: Developers may fail before the first successful local run: Build in public — show Palinode building Palinode
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/33

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: CLAUDE.md integration — zero-friction adoption path
- User impact: Developers may fail before the first successful local run: CLAUDE.md integration — zero-friction adoption path
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/32

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Directory submissions — MCP Registry, Smithery, mcp.so, Cline
- User impact: Developers may fail before the first successful local run: Directory submissions — MCP Registry, Smithery, mcp.so, Cline
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/35

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Docs: public integration guide for OpenClaw and Hermes-agent
- User impact: Developers may fail before the first successful local run: Docs: public integration guide for OpenClaw and Hermes-agent
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/60

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Homebrew tap (brew install palinode)
- User impact: Developers may fail before the first successful local run: Homebrew tap (brew install palinode)
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/8

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code)
- User impact: Developers may fail before the first successful local run: Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code)
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/24

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.8.13
- User impact: Upgrade or migration may change expected behavior: v0.8.13
- Evidence: failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.13

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.8.15
- User impact: Upgrade or migration may change expected behavior: v0.8.15
- Evidence: failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.15

## 11. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/61

## 12. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/33

## 13. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/32

## 14. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/60

## 15. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/8

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/2

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/24

## 18. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/phasespace-labs/palinode

## 19. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Ambient context search: automatic project-aware retrieval (ADR-008)
- User impact: Developers may misconfigure credentials, environment, or host setup: Ambient context search: automatic project-aware retrieval (ADR-008)
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/28

## 20. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Anthropic Connectors Directory: submission prep
- User impact: Developers may misconfigure credentials, environment, or host setup: Anthropic Connectors Directory: submission prep
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/29

## 21. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle
- User impact: Developers may misconfigure credentials, environment, or host setup: Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/17

## 22. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.8.12
- User impact: Upgrade or migration may change expected behavior: v0.8.12
- Evidence: failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.12

## 23. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.8.14
- User impact: Upgrade or migration may change expected behavior: v0.8.14
- Evidence: failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.14

## 24. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/phasespace-labs/palinode

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: Migrate plugin from before_agent_start to before_prompt_build
- User impact: Developers may hit a documented source-backed failure mode: Migrate plugin from before_agent_start to before_prompt_build
- Evidence: failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/2

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/phasespace-labs/palinode

## 27. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/phasespace-labs/palinode

## 28. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/phasespace-labs/palinode

## 29. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/62

## 30. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/29

## 31. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/35

## 32. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/phasespace-labs/palinode/issues/17

## 33. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/phasespace-labs/palinode

## 34. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/phasespace-labs/palinode

<!-- canonical_name: phasespace-labs/palinode; human_manual_source: deepwiki_human_wiki -->