File tree

72 files, 793 nodes. Open a folder, then a file, to see what it defines.

./ 8 files

.mcp.json 0 symbols

AGENTS.md 1 symbols

Cairn — project memory section L2

CHANGELOG.md 2 symbols

Changelog section L1
0.1.0 — 2026-09-24 section L3

CLAUDE.md 1 symbols

Cairn — project memory section L2

CONTRIBUTING.md 4 symbols

Contributing section L1
How we work section L10
Code map section L16
Rules of thumb section L26

README.md 9 symbols

Cairn section L1
Documentation section L102
Licence section L112
Why section L14
What you get on day one (no API key) section L29
And over time section L45
The terminal section L61
Commands section L77
Install options section L92

install.sh 1 symbols

say() function L6

pyproject.toml 0 symbols

docs/ 6 files

agents.md 3 symbols

Agent integrations section L1
Sub-agents (Claude Code), tiered by model section L16
Session capture section L28

architecture.md 6 symbols

Architecture section L1
Shape section L3
Principles in code section L38
Data flow of a sync section L49
The context assembler section L61
Canonical ids section L69

cli.md 8 symbols

docs/cli.md section L1
CLI reference section L1
Questions section L15
Map section L27
Specs section L31
Memory, timeline, sessions section L39
Servers and agents section L44
Setup and health section L5

configuration.md 1 symbols

Configuration section L1

mcp.md 2 symbols

MCP tools section L1
docs/mcp.md section L1

models-and-cost.md 4 symbols

Models and cost section L1
Keeping tokens down section L10
Ledger section L18
Routing section L6

docs/adr/ 6 files

0001-unified-read-model.md 5 symbols

ADR-0001: One read model for every surface section L1
Decision section L10
Options considered section L15
Consequences section L22
Context section L5

0002-deterministic-first.md 4 symbols

ADR-0002: Deterministic first, models second section L1
Consequences section L15
Context section L5
Decision section L9

0003-embedded-temporal-store.md 4 symbols

ADR-0003: Embedded temporal store by default section L1
Decision section L10
Consequences section L15
Context section L5

0004-model-routing.md 4 symbols

ADR-0004: Task-tiered model routing section L1
Consequences section L15
Context section L5
Decision section L9

0005-invisible-engines.md 4 symbols

ADR-0005: One product, invisible engines section L1
Exceptions, stated honestly section L16
Context section L5
Decision section L9

0006-built-in-session-capture.md 4 symbols

ADR-0006: Session capture is built in section L1
Decision section L12
Consequences section L19
Context section L5

specs/001-cairn-core/ 7 files

analysis.md 4 symbols

Analysis: 001-cairn-core (cross-artifact consistency) section L1
Consistency findings section L36
Measured (httpx, 101 source files, shallow 50 commits; sandbox CPU) section L46
Requirement coverage section L6

data-model.md 4 symbols

Data Model: Cairn read model (`.cairn/brain.db`) section L1
Canonical ids section L16
Link rules (linker) section L21
State transitions section L32

plan.md 8 symbols

Implementation Plan: Cairn Core section L1
Technical Context section L13
Constitution Check section L29
Project Structure section L42
Documentation (this feature) section L44
Summary section L5
Source Code (repository root) section L53
Complexity Tracking section L87

quickstart.md 1 symbols

Quickstart validation section L1

research.md 9 symbols

Research: Cairn Core section L1
R2 Spec workflow integration section L15
R3 Temporal fact graph section L24
R4 Semantic memory section L32
R5 Session capture section L39
R6 MCP SDK section L49
R1 Code map engine output section L5
R7 Model routing & cost section L53
R8 UI section L59

spec.md 19 symbols

Feature Specification: Cairn Core — the engineering brain section L1
User Story 5 — Memory that compounds (Priority: P2) section L102
User Scenarios & Testing *(mandatory)* section L11
User Story 6 — One page to see everything (Priority: P2) section L122
User Story 1 — One command on an existing repo (Priority: P1) section L13
User Story 7 — Premium agent experience everywhere (Priority: P3) section L133
User Story 8 — Deep tier when a key is present (Priority: P3) section L144
Edge Cases section L154
Clarifications section L165
Session 2026-09-24 section L167
Requirements *(mandatory)* section L185
Functional Requirements section L187
Key Entities section L219
Success Criteria *(mandatory)* section L229
Measurable Outcomes section L231
Assumptions section L240
User Story 2 — "What breaks if I change this?" (Priority: P1) section L38
User Story 3 — "Why is this code like this?" (Priority: P2) section L62
User Story 4 — Spec-driven work with memory (Priority: P2) section L80

tasks.md 14 symbols

Tasks: Cairn Core section L1
Phase 2: Foundational (blocks all stories) section L15
Phase 3: US1 — One command on an existing repo (P1) 🎯 MVP section L22
Phase 4: US2 — Impact (P1) section L32
Phase 5: US3 — Why (P2) section L38
Phase 6: US4 — Spec-driven work with memory (P2) section L43
Phase 7: US5 — Memory that compounds (P2) section L51
Phase 8: US6 — One page (P2) section L58
Phase 9: US7 — Premium agent experience (P3) section L64
Phase 10: US8 — Deep tier (P3) section L71
Phase 11: Polish section L78
Dependencies section L85
Phase 1: Setup section L9
Converge (remaining work, appended by T043) section L91

specs/001-cairn-core/contracts/ 3 files

cli.md 2 symbols

contracts/cli.md section L1
CLI contract section L1

http.md 1 symbols

HTTP contract (daemon, `127.0.0.1:4747`) section L1

mcp.md 2 symbols

contracts/mcp.md section L1
MCP contract (server name `cairn`, stdio) section L1

src/cairn/ 16 files

__init__.py 0 symbols

__main__.py 0 symbols

agents.py 14 symbols

merge_json() function L103
write_generated() function L117
_hook_cmd() function L132
_capture_cmd() function L142
install() function L147
note() function L154
settings() function L163
uninstall() function L210
clean() function L220
command() function L29
detect() function L36
installed() function L52
upsert_block() function L75
remove_block() function L89

capture.py 9 symbols

record() function L108
main() function L128
store_path() function L36
find_root() function L40
redact() function L49
mask() function L51
_rel() function L60
events_for() function L71
_enabled() function L98

cli.py 52 symbols

stones() function L111
main_cb() function L140
init() function L157
run_init() function L167
view() function L186
mark() function L198
prog() function L245
status() function L277
_ago() function L299
doctor() function L305
row() function L319
sync_cmd() function L359
prog() function L368
impact() function L384
_cairn() function L40
why() function L402
_narrate() function L416
ask() function L427
search() function L445
brief() function L458
trace_path() function L465
trace_explain() function L472
trace_query() function L479
hubs() function L486
areas() function L494
_need_init() function L50
prs() function L501
specs() function L510
spec_new() function L540
drift() function L549
_emit_json() function L56
remember() function L574
recall() function L587
memories() function L601
forget() function L609
timeline() function L617
_emit_pack() function L63
sessions() function L631
ui() function L651
up() function L662

core.py 42 symbols

.mark_sent() method L114
.accounting() method L120
.sections() method L126
Cairn class L133
.__init__() method L136
.here() method L144
.map() method L151
.budget_default() method L155
.resolve() method L159
.source_cost() method L193
._logger() method L205
log() function L210
._cited_files() method L216
._intent() method L228
._sessions() method L253
._memories() method L261
._facts() method L266
.impact() method L276
ago() function L30
.why() method L348
.infer_targets() method L386
day() function L40
.context() method L403
.ask() method L437
Item class L45
.narrate() method L453
.remember() method L466
.active_spec() method L473
.overview() method L484
.brief() method L517
.line() method L52
.architecture() method L554
roll() function L566
Target class L57
.agent_activity() method L576
.savings() method L592
.search() method L596
_recency() function L610
.found() method L65
Pack class L70

daemon.py 5 symbols

_free() function L16
_health() function L22
info() function L30
start() function L44
stop() function L67

drift.py 4 symbols

record() function L104
_finding() function L19
check() function L25
semantic() function L63

hooks.py 5 symbols

_line() function L20
install_git_hooks() function L25
remove_git_hooks() function L45
session_start() function L60
statusline() function L70

linker.py 4 symbols

ingest_map() function L23
mention_index() function L59
link_text() function L71
relink_memories() function L94

mcp_server.py 11 symbols

main() function L102
_cairn() function L15
cairn_context() function L21
cairn_impact() function L26
cairn_why() function L31
cairn_search() function L36
cairn_trace() function L42
cairn_specs() function L52
cairn_remember() function L72
cairn_recall() function L78
build() function L91

project.py 18 symbols

.dir() method L102
.config_path() method L106
.db_path() method L110
.map_dir() method L114
.map_json() method L118
.initialized() method L122
.is_git() method L126
.rel() method L129
.ensure_dir() method L137
.git() method L145
.cfg() method L154
_merge() function L48
find_root() function L55
Project class L65
.discover() method L71
.reload() method L82
.name() method L93
.id() method L97

router.py 19 symbols

.deep_enabled() method L102
.model() method L108
.table() method L113
.tier_for() method L120
.complete() method L128
._anthropic() method L155
._claude_code() method L176
._openai() method L201
BudgetExceeded class L37
Budget class L42
.remaining() method L47
.check() method L50
.charge() method L54
estimate_tokens() function L58
resolve_provider() function L65
Router class L79
.__init__() method L80
.api_key() method L89
.available() method L99

server.py 30 symbols

savings() function L103
specs() function L107
drift() function L112
memories() function L117
add_memory() function L121
forget() function L129
timeline() function L133
sessions() function L137
ask() function L145
start_sync() function L149
work() function L154
stream() function L166
gen() function L170
models() function L184
brief() function L189
serve() function L195
create_app() function L20
lifespan() function L28
broadcast() function L35
index() function L42
health() function L46
overview() function L50
map_() function L57
entity() function L64
search() function L77
_pack() function L80
impact() function L87
why() function L91
architecture() function L95
agent_activity() function L99

store.py 35 symbols

.tx() method L102
.q() method L112
.one() method L116
.close() method L120
.get_kv() method L125
.set_kv() method L129
.put_entities() method L136
.put_entity() method L151
.drop_source() method L155
.link() method L167
.entity() method L177
.entities() method L181
.by_path() method L184
.links_to() method L188
.links_from() method L199
.counts() method L210
.search() method L217
.add_events() method L235
.events() method L244
.add_memory() method L261
.memories() method L280
.memory() method L286
.forget() method L290
.cochanged() method L297
.filestat() method L311
.log_call() method L316
.ledger() method L324
.log_query() method L331
.queries() method L341
.query_totals() method L344
_ent() function L351
searchable() function L71
fts_query() function L77
Brain class L87
.__init__() method L90

sync.py 8 symbols

_summary() function L107
spawn_background() function L123
locked() function L24
run() function L41
step() function L52
do_map() function L64
do_drift() function L83
do_deep() function L93

src/cairn/engines/ 7 files

__init__.py 0 symbols

chronicle.py 16 symbols

._driver() method L107
.pending_episodes() method L125
.ingest() method L154
._mirror() method L185
.search() method L205
facts_matching() function L219
dumps() function L232
_local_embedder() function L30
__init__() function L36
create() function L40
create_batch() function L45
_lexical_reranker() function L52
rank() function L58
Chronicle class L70
.__init__() method L71
.engine() method L77

history.py 7 symbols

_is_ancestor() function L131
risky_for() function L140
recent_for() function L153
origins() function L158
risk_tags() function L24
_parse() function L35
ingest() function L66

journal.py 7 symbols

for_files() function L120
available() function L20
installed() function L25
_turns() function L34
_kind() function L53
_migrate() function L57
ingest() function L68

mapper.py 31 symbols

.__len__() method L120
.edge_count() method L123
.label() method L126
.file_of() method L130
.is_code() method L133
.degree() method L136
.describe() method L140
.resolve() method L147
.members() method L180
.dependents() method L194
.dependencies() method L218
._line() method L227
._span() method L231
.rationale() method L241
add() function L246
.hubs() method L269
.areas() method L273
.area_graph() method L290
.area_members() method L309
key() function L31
.file_graph() method L320
_engine() function L36
.languages() method L360
_components() function L369
index() function L416
ensure_ignores() function L44
build() function L51
engine_text() function L66
Edge class L77
MapIndex class L85
.load() method L96

memory.py 12 symbols

.remember() method L100
.recall() method L131
.about() method L146
SemanticMemory class L21
.__init__() method L26
.ready() method L32
._engine() method L35
.add() method L64
.search() method L75
.history() method L86
MemoryStore class L94
.__init__() method L95

specs.py 12 symbols

paths_in() function L106
parse_feature() function L121
constitution() function L155
features() function L164
ingest() function L171
cli() function L27
initialized() function L36
bootstrap() function L40
install_extension() function L58
new_feature() function L76
_unwrap() function L87
_read() function L99

src/cairn/templates/ 1 files

instructions.md 1 symbols

Cairn — project memory section L1

src/cairn/templates/claude/agents/ 4 files

cairn-architect.md 0 symbols

cairn-implementer.md 0 symbols

cairn-reviewer.md 0 symbols

cairn-scout.md 0 symbols

src/cairn/templates/claude/commands/ 6 files

ask.md 0 symbols

brief.md 0 symbols

drift.md 0 symbols

impact.md 0 symbols

remember.md 1 symbols

claude/commands/remember.md section L1

why.md 0 symbols

src/cairn/workflow_extension/ 1 files

README.md 2 symbols

workflow_extension/README.md section L1
Cairn extension for the spec workflow section L1

src/cairn/workflow_extension/commands/ 4 files

context.md 6 symbols

User Input section L10
Steps section L14
Step 1: Find the code this feature touches section L16
Step 2: Check each likely change point section L20
Step 3: Feed the plan section L24
Ground the plan in the project's memory section L8

remember.md 3 symbols

workflow_extension/commands/remember.md section L1
Save clarifications as decisions section L5
Steps section L7

trace.md 5 symbols

Step 2: Review risk per task section L12
Step 3: Report section L18
Trace tasks to code section L5
Steps section L7
Step 1: Refresh the memory section L9

verify.md 5 symbols

Steps section L10
Step 1: Sync and check drift section L12
Step 2: Resolve findings section L15
Step 3: Capture learnings section L18
Verify against the spec section L8

tests/ 3 files

conftest.py 4 symbols

git() function L15
commit() function L19
repo() function L76
cairn() function L94

test_core.py 24 symbols

test_capture_groups_turns_and_finishes_them_on_the_next_sync() function L110
test_capture_is_silent_outside_cairn_repos_and_when_disabled() function L125
test_capture_hook_is_light_and_never_fails() function L133
test_drift_ids_are_stable_across_processes() function L144
test_drift_record_is_idempotent_and_keeps_first_seen() function L155
test_sync_links_summary_names_what_it_counts() function L165
test_session_paths_keep_dotfolders() function L170
test_pack_accounting_matches_render_and_logs_once() function L179
test_only_packs_handed_out_are_logged() function L190
test_source_cost_counts_existing_files_once() function L196
test_file_graph_layers_and_cycles() function L201
test_risk_tags() function L21
test_wrapped_requirements_are_read_whole() function L219
test_sync_builds_all_layers() function L27
test_impact_has_dependents_warnings_and_owners() function L35
test_budget_is_respected() function L45
test_why_includes_rationale_and_origin() function L52
test_memory_links_to_code() function L58
test_specs_parser_and_drift() function L66
test_context_infers_targets() function L76
test_brief_is_small() function L82
_hook() function L87
test_store_search_and_memory() function L9
test_capture_records_prompts_files_and_commands() function L92

test_surfaces.py 13 symbols

test_doctor_shows_bracketed_fixes_and_wired_agents() function L108
test_http_views_for_the_page() function L117
test_init_is_zero_prompt_and_idempotent() function L13
test_session_briefing_counts_as_cost() function L132
test_mcp_tool_calls_count_as_agent_context() function L138
test_cli_json_is_counted_and_stays_lean() function L148
test_uninstall_removes_only_ours() function L34
test_status_and_questions_via_cli() function L49
test_hooks_output() function L58
test_http_api() function L64
test_mcp_tools() function L78
test_statusline_shows_spec_number() function L91
test_installed_agents_reads_configs() function L97