Capture context. Compound knowledge.
CarpeOS is a personal knowledge OS for AI-assisted work. It captures agent
sessions with provenance, forms durable meaning at write time (cheap
adj_v3 rules plus a post-capture Agentic Layer), keeps promoted decisions
searchable by default, and helps you and your agents retrieve that context later
via MCP, CLI, and Obsidian — all local-first, without required human review
on the happy path.
It keeps the trail of where each piece came from without turning every session dump into “memory.”
Latest package: @innocarpe/carpeos@6.6.4
(CHANGELOG · v6.6.4).
Visit the CarpeOS website for the product overview, system model, install path, and public documentation guide.
You finish a long agent session with a real decision, a half-finished plan, or a bug path you do not want to rediscover. A week later that context is split across chat history, terminal scrollback, and a few notes — and the next agent has none of it.
CarpeOS is an attempt to keep that context in one place you control, with enough structure that “we decided X” is not treated the same as “the model once suggested X.”
| Common problem | Approach here |
|---|---|
| Chat history disappears or is hard to trust | Append-only events with provenance |
| Session noise floods “memory” | Post-capture adjudication + agentic gate; default search is promoted only |
| Next agent forgets last session’s decisions | HITL-free Agentic Layer promotes verified meaning for default retrieval |
| “Memory” is mostly embeddings | Claims, acceptance, and supersession stay separate records |
| Each tool keeps its own silo | Shared capture + MCP retrieval, provider-agnostic |
| Generated notes become the only source of truth | Notes and indexes are rebuildable projections |
| Two machines, messy continuity | Local-first store, optional private sync |
Public code. Private knowledge.
This repo has design, specs, and implementation. Your real sessions, projects, and credentials stay on your side.
Useful if you:
- Switch between agents (Codex, Claude Code, Grok Build, …) and do not want a separate memory story for each one
- Need last week’s decisions still available, not buried in an old transcript
- Care whether something is a draft, rejected, or actually accepted when you search for it
- Want data local by default, with sync you run yourself if you need it
- Prefer explicit schemas and tests over a black-box “memory product”
Not a polished consumer app yet. Not hosted SaaS. Not a replacement for your editor. Closer to plumbing for people who already live in agent workflows.
Hooks map selected lifecycle events from Codex, Claude Code, and Grok Build into a common capture shape. Raw payloads sit in encrypted storage; the event log keeps metadata and references. Host hooks stay fail-open and fast.
After capture, two write-time paths can assign what is worth keeping:
| Plane | Role | Default path |
|---|---|---|
adj_v3 |
Cheap rule prefilter / noise reject | Still available; comparison baseline |
Agentic Layer (agentic_v1) |
Typed, cited brain (Flash-only when network on) | Product 6 happy path from 6.6.0 |
| Disposition | Meaning unit | Default search |
|---|---|---|
| promote | Active Observation | Included |
| hold | Draft Observation (side channel) | Excluded unless --include-held / include_held |
| reject | Disposition only (evidence may remain) | Excluded |
Agentic (ADR 0018): verified allowlisted extracts (decision /
constraint / preference) promote by default when E5 grounds the
statement in cited spans — no human click required. procedure and
fact_candidate stay hold-biased. Humans retract mistakes, optionally
accept-claim, or clear holds — correction only.
Held review remains policy-aware and append-only for both planes. Neither path
automatically creates an AcceptanceDecision.
adj_v3 foundation (3.2+) and B0 policy reconciliation preview remain available:
carpeos adjudicate reconcile-policy \
--from-policy adj_v1 --to-policy adj_v3 \
--trust-zone tz_synthetic --limit 100B0 is metadata-only and supports only these exact flags: --from-policy, --to-policy,
--trust-zone, and --limit. --apply, --apply-safe-subset, acknowledgements, receipts,
and Supersession construction are unsupported. B1 write/apply/receipt work remains deferred.
Dogfood inputs and outputs are synthetic and disposable.
Evidence is not a claim. A claim is not “true” just because it exists. Acceptance and supersession are their own records. Search can show what is settled, what is only proposed, and what was replaced — without stuffing it all into one paragraph of vector text.
flowchart LR
E[EvidenceArtifact] --> Feed[agentic_capture_feed]
E --> J[adj_v3 optional]
Feed --> Ag[Agentic E1–E8]
Ag -->|promote-when-verified| O[Observation active]
Ag -->|hold side channel| H[Observation draft]
Ag -->|reject| R[Evidence only]
J -->|promote| O
J -->|hold| H
O --> C[Claim draft optional]
C --> A[AcceptanceDecision<br/>human only]
O --> S[Supersession<br/>human retract]
A --> F[Accepted fact<br/>derived at query time]
S --> F
- CLI —
capture-hook,extract,adjudicate,agentic(run / timer / retract / golden / graphrag…),retrieval rebuild,memory search|get|context-pack(default promoted-only;--include-heldopt-in),sync status|push|pull|once|cycle - MCP (stdio) — eight local tools (
memory_search,memory_get,memory_context_pack,memory_trace,memory_timeline,memory_related,memory_capture,memory_propose_claim) - Always-on agentic — optional 30m timer:
carpeos agentic timer install(network off by default) - Obsidian projection — Markdown files generated from the local store (projection only; not the source of truth)
- OKF v0.2 export projection —
carpeos okf export|rebuildwrites a trust-zone-scoped, promoted/active-by-default portable bundle; it is not canonical storage or an import path (guide)
Each machine writes to a local outbox. There is deployable Cloudflare
Worker/D1/R2 code if you want private multi-device sync, plus a bounded
carpeos sync cycle for operator loops. Projections can always be rebuilt from
the event log.
flowchart TB
subgraph devices [Your machines]
H1[Agent hooks]
CLI[carpeos CLI]
MCP[MCP stdio server]
OBS[Obsidian projection]
end
subgraph local [Local runtime]
OUT[Encrypted outbox + local store]
RET[Search + recheck]
end
subgraph private [Optional private sync]
W[Cloudflare Worker]
D1[(D1 metadata)]
R2[(R2 encrypted blobs)]
end
H1 --> OUT
CLI --> OUT
OUT --> RET
RET --> MCP
RET --> OBS
OUT <--> W
W --> D1
W --> R2
flowchart TB
A[Agent hooks<br/>fail-open] --> B[Local capture<br/>no LLM]
B --> F1[agentic_capture_feed]
B --> F2[adj_v3 optional]
F1 --> T[30m timer or<br/>agentic run]
T --> G[E5 ground + gate<br/>promote-when-verified]
G --> C[Event store]
F2 --> C
C --> D[Promoted / active meaning]
C --> E[Projections]
D --> M[MCP / CLI / Obsidian]
E --> M
H[Human retract / accept<br/>correction only] -.-> C
Rules worth knowing up front:
- The event log is append-only; dispositions are append-only by policy version.
- Default search is promoted/active meaning — not every captured session.
- Agentic promote-when-verified closes the loop without load-bearing HITL
(ADR 0018); formal
AcceptanceDecisionis still human-only and optional. - “Accepted” is computed at query time — we do not rewrite a claim in place.
- Sensitive plaintext is not stored inside the event body.
- Trust zones are real isolation boundaries, not labels for show.
- Notes, vectors, and context packs can be deleted and rebuilt; they are not the canonical store.
More detail: Architecture overview, Agentic Layer, Memory capacity, ADR 0017, ADR 0018, ADRs, spec/v1.
CarpeOS separates how much private knowledge you store from how much an agent loads right now:
| Axis | Meaning | Where it lives |
|---|---|---|
| Total capacity | Visible append-only events + protected blobs under trust zones | L1 store |
| Active capacity | What fits a bounded pack or search response after budgets and recheck | L2 working memory |
| Procedural memory | Thinking/tool traces as protected evidence, never auto-accepted | L3 |
| Product projections | Rebuildable notes, packs, open loops, dashboards | L4 |
Context packs use sparse expert-slot allocation (default 16 slots) and a cache-friendly section order so accepted facts stay ahead of high-churn drafts. See the memory capacity architecture note and the capacity master plan. Retrieval-first graph/hybrid recall — including cross-repository partitioning and worktree facets — shipped in 3.0; hosted graph adapters and other roadmap work remain planned. See the product 3.0 DoD and GraphRAG roadmap.
Requires Node.js ≥ 22.22.
# npm (preferred)
npm install -g @innocarpe/carpeos
carpeos setup plan # see paths + actions (no changes)
carpeos setup run --apply # apply defaults
# or curl (installs the same package, then setup run --apply)
curl -fsSL https://raw.githubusercontent.com/innocarpe/carpeos/main/scripts/install.sh | bashcarpeos setup is a real CLI surface — not a flag dump. Default paths land under
~/.carpeos and ~/.local/bin; MCP registers with Claude Code / Codex CLI /
Grok Build when those tools are on PATH.
carpeos setup --help # full parameter interface
carpeos setup plan # resolved plan only
carpeos setup run --apply # apply the plan (home, wrappers, MCP)
carpeos setup hooks install --apply # capture hooks (merge-safe; product path)
carpeos setup doctor # verify install + hooks + store signals
carpeos setup show # print config.jsonUseful options: --home, --bin-dir, --workspace-root, --trust-zone,
--register-mcp auto|none|claude,codex,grok, --register-hooks auto|none|….
Setup never mutates the machine without --apply.
Pin a version when you care about reproducibility:
npm i -g @innocarpe/carpeos@6.6.4. See CHANGELOG.md.
Milestone DoDs (maintainers): docs/maintainers/ ·
product index: docs/PRD.md.
git clone https://github.com/innocarpe/carpeos.git && cd carpeos
node scripts/install-local.mjs plan
node scripts/install-local.mjs run --apply # build, wrappers, MCP registration
node scripts/install-local.mjs hooks install --apply
export PATH="$HOME/.local/bin:$PATH"
node scripts/install-local.mjs doctorFor monorepo work without global install: pnpm install && pnpm build, then use
node apps/carpeos-cli/dist/index.js … (see local capture).
# 1) Runtime + MCP
carpeos setup run --apply
# 2) Capture hooks (Claude / Codex / Grok; merge-safe, does not wipe user hooks)
carpeos setup hooks install --apply
# 3) Always-on Agentic brain (30 minutes; network off by default)
carpeos agentic timer install
# 4) Doctor (hooks, store, adjudication health, promoted-only default search)
carpeos setup doctor
# 5) After a host session, meaning compounds without manual review:
# capture → feed → agentic run (timer or:)
carpeos agentic run --once --materialize
carpeos retrieval rebuild --trust-zone tz_local_default
carpeos memory search \
--query "durable decision" \
--trust-zone tz_local_default \
--visible-trust-zone tz_local_default
# Correction only (not the happy path)
# carpeos agentic retract --event-id evt_… --reason "…" --decided-by human --human-confirmed
# carpeos agentic promote-held --event-id evt_…
# carpeos adjudicate list-held --limit 50
# Kill / staging
# CARPEOS_AGENTIC=off …
# CARPEOS_AGENTIC_HOLD_FIRST=1 carpeos agentic run --once --materializecarpeos setup doctor reports hook install status, recent EvidenceArtifact
activity, Observation/Claim counts, adjudication policy version + promote/hold/reject
counts, and that default search is promoted/active only (empty store → warnings,
not fail).
Automated gates:
| Gate | What it proves |
|---|---|
pnpm smoke:product |
1.0 pipeline loop (capture → extract path → search) |
pnpm smoke:knowledge |
2.0 promote vs noise reject |
pnpm smoke:dogfood |
multi-hook public-safe noise scenarios |
pnpm smoke:mcp |
MCP tool surface |
Advanced/manual hook templates remain under adapters/. Full notes:
one-stop install ·
MCP ·
product smoke.
Read AGENTS.md first (public/private boundary, PR labels, release
skill, install rules). Keep installs idempotent; never commit ~/.carpeos, credentials,
or real session data. Prefer carpeos setup / scripts/install-local.mjs — do not invent
alternate install paths. Releases: SemVer + vX.Y.Z only
(versioning,
major release surface,
skills/carpeos-release/SKILL.md).
Current npm package is @innocarpe/carpeos@6.6.4 (v6.6.4): operator loop through
adjudication + retrieval, Product 4 trust plane, opt-in Product 5 draft lane, and
Product 6 HITL-free Agentic Layer (post-capture Flash brain;
promote-when-verified, retract, day spend, 30m timer — ADR 0018; capture
stays dumb; human tools are correction-only).
Full major/minor thesis and DoD index:
- docs/PRD.md — one PRD per major
- docs/architecture/agentic-layer.md — service map
- docs/maintainers/ —
product-N.0.0.mdreceipts (e.g. 6.0.0, 5.0.0)
Honest residuals (do not invent green): live Product 4 release authority out of band; B1 apply deferred; hosted graph/edge not claimed; V5 never on capture hot path; procedure auto-promote still hold-biased; live Flash remains opt-in network.
Public package: @innocarpe/carpeos@6.6.4
(v6.6.4 · CHANGELOG). npm install does not imply hosted deploy or
live Product 4 release authority.
Default local loop (CI-gated):
hooks → encrypted evidence → agentic_capture_feed (no LLM in capture)
→ agentic run / 30m timer (promote-when-verified)
→ active Observations in default search
→ retrieval-first graph/hybrid recall → MCP / CLI
(+ adj_v3 baseline, local OKF export, optional private sync, Obsidian)
# Kill: CARPEOS_AGENTIC=off
# Staging: CARPEOS_AGENTIC_HOLD_FIRST=1
# Offline (no Flash): CARPEOS_AGENTIC_NETWORK=off or --allow-network false
# Credentials: DEEPSEEK_API_KEY or ~/.carpeos/v5-provider.env
| Area | Status |
|---|---|
| Specs, ontology, ADRs | In tree (incl. ADR 0012, 0017, 0018) |
| Local capture + outbox | Shipped |
Knowledge adjudication (adj_v3) |
Shipped in 3.2 — precision/session de-noising; no automatic Claim or AcceptanceDecision |
| Default retrieval | Promoted/active only; held opt-in |
| Doctor adjudication health | Shipped (setup doctor, adjudicate --stats) |
Sync Worker/client + bounded sync cycle |
Code + local tests; no production edge claimed |
| MCP stdio server (8 tools) | Local only |
| Expert-slot context packs | CLI + MCP (local) |
| Retrieval-first graph/hybrid recall | Shipped — GraphRAG typed boosts in 6.4 |
| Hosted graph adapters / services | Planned; not shipped or deployed |
| OKF v0.2 export projection | Shipped in 3.1 — local export only; no import path |
| Product 3.x–5.x | Shipped — see product DoDs under docs/maintainers/ |
Product 6 Agentic Layer (carpeos agentic) |
HITL-free shipped in 6.6.0 — promote-when-verified, retract, day spend, 30m timer; product-6.0.0, agentic-layer |
carpeos setup / one-stop install |
Shipped (@innocarpe/carpeos) |
| OpenLoop / dashboard library | Library + tests; not a shipped UI |
| Obsidian projection | Local only |
| Hosted embeddings / multi-tenant SaaS | Not goals of this repo |
NOT DEPLOYED: no hosted Worker, D1/R2 production resources, hosted graph adapters/services, private vault adoption, or hosted MCP is proven by this repository. npm publish is gated by SemVer tags + CI (versioning).
Do not treat adapter install, a live Cloudflare setup, hosted MCP, or calibrated human-level judgment as finished until this repo says so with tests and docs.
Public implementation only. Runtime knowledge stays private.
| OK here | Not OK here |
|---|---|
Synthetic fixtures (Example Alpha, …) |
Real project names or private URLs |
| Protocol examples | Real session transcripts |
| Tests and schemas | Credentials, tokens, production logs |
| Contributor docs | Runtime DB dumps, personal paths |
Some ideas overlap with obsidian-mind (agent memory, hooks, retrieval for agents). CarpeOS is a separate design: append-only events instead of a Markdown vault as authority, explicit claim/acceptance/supersession, trust zones, protected values, and MCP that is not locked to one vendor.
See CONTRIBUTING.md, GOVERNANCE.md, and AGENTS.md.
pnpm check # format, lint, build, typecheck, test, public-boundaryPublic package releases use one shared process (any coding agent should follow the same skill):
./scripts/install-release-skill.sh # Claude / Codex / Grok skill links
# then: release / tag / npm — see skills/carpeos-release/SKILL.md