You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Grounded, auditable memory for coding agents—stored beside the code, protected by Git, and traceable to evidence.
7
+
Grounded, auditable memory for coding agents—stored beside the code, reviewable in
8
+
Git, and traceable to exact evidence.
8
9
9
-
Agents forget context and can repeat stale conclusions. GraphKeeper gives every durable finding a stable subject, provenance, and history. The store is plain JSON plus immutable evidence files, so humans can diff it, `jq` can query it, and a pre-commit hook can stop accidental rewrites.
10
+
GraphKeeper is not a transcript store or a generic memory wrapper. It records durable
11
+
project findings as flat claims linked to the run and evidence that produced them.
12
+
When a finding becomes outdated, a new claim explicitly supersedes it; the old claim
13
+
stays in Git history for review. The result is memory that Codex, Claude Code, and
14
+
humans can inspect without trusting an opaque summary or hosted service.
15
+
16
+
The core flow is deliberately small:
17
+
18
+
1. An agent discovers a stable project fact and captures the relevant output under
19
+
`evidence/`.
20
+
2. It appends an entity, run, and evidence-backed claim to `graph/`.
21
+
3.`graphkeeper check` validates schema, provenance, and append-only history against
22
+
the committed Git state.
23
+
4. A future session retrieves the active claim with `graphkeeper query <subject>`.
24
+
5. If the fact changes, the agent appends a new claim with `supersedes`; both
25
+
generations remain auditable.
26
+
27
+
GraphKeeper does not ingest conversations or decide what should become memory. The
28
+
shipped Codex and Claude Code skills give agents the same explicit writing contract.
`init` creates an empty `graph/`, an `evidence/` directory, the repository-scoped
54
-
Codex skill at `.agents/skills/graphkeeper/SKILL.md`, the canonical validator, and a
55
-
pre-commit hook. Codex discovers that skill from its standard repository skill path
56
-
and loads its full instructions when `$graphkeeper` is invoked or the request clearly
57
-
matches its description. The hook normally lives under `.git` and is not committed;
58
-
`.githooks/pre-commit` exists only when GraphKeeper must preserve and chain another
59
-
hook. An empty `evidence/` directory becomes tracked when the first evidence file is
60
-
added.
61
-
62
-
For a complete agent integration (the agent-specific skill plus a short,
63
-
always-visible reminder), opt in explicitly:
64
-
65
-
```sh
66
-
npx graphkeeper init --integrate codex
67
-
npx graphkeeper init --integrate claude
68
-
npx graphkeeper init --integrate all
65
+
npx graphkeeper@latest init --integrate codex
66
+
# Or: npx graphkeeper@latest init --integrate claude
67
+
# Or: npx graphkeeper@latest init --integrate all
68
+
npx graphkeeper@latest check
69
69
```
70
70
71
-
Codex uses `.agents/skills/graphkeeper/SKILL.md`, `AGENTS.md`, and
71
+
Review the displayed plan and confirm it. `init` creates the JSON graph, `evidence/`,
72
+
the canonical validator, a pre-commit hook, and the repository-scoped Codex skill.
73
+
`--integrate codex` adds the Codex reminder to `AGENTS.md`; `--integrate claude` adds
74
+
the Claude skill and reminder; `--integrate all` does both. Codex uses
75
+
`.agents/skills/graphkeeper/SKILL.md`, `AGENTS.md`, and
72
76
`$graphkeeper`. Claude Code uses `.claude/skills/graphkeeper/SKILL.md`,
73
77
`CLAUDE.md`, and `/graphkeeper`. Both skills are generated from the same
74
78
`templates/SKILL.md`. Existing guidance outside the matching marked block is
@@ -77,18 +81,31 @@ preserved. Integration plans are shown before writing; answer the prompt, or pas
77
81
preflight. Default init and `--force` do not create or change `AGENTS.md` or
78
82
`CLAUDE.md`.
79
83
80
-
When an agent records a finding, retrieve it by canonical entity ID or an exact unique alias:
84
+
Ask the selected agent to record a verified finding with `$graphkeeper` in Codex or
85
+
`/graphkeeper` in Claude Code. After it writes the claim and evidence, validate and
86
+
retrieve the result:
81
87
82
88
```sh
89
+
npx graphkeeper check
83
90
npx graphkeeper query test_payments_flaky
84
91
npx graphkeeper doctor
85
92
```
86
93
87
-
To try populated data from a source checkout, copy `examples/worked-example/graph` and `examples/worked-example/evidence` into a temporary Git repository and query `test_payments_flaky`.
94
+
Commit the generated graph, validator, agent skills, and guidance files. The hook
95
+
normally lives under `.git` and is not committed;
96
+
`.githooks/pre-commit` is created only when GraphKeeper must preserve and chain another
97
+
hook. An empty `evidence/` directory becomes tracked with the first captured artifact.
98
+
99
+
To try the full discovery-to-supersession flow with populated data, copy
100
+
`examples/worked-example/graph` and `examples/worked-example/evidence` into a temporary
101
+
Git repository, then query `test_payments_flaky`.
88
102
89
103
## Before and after
90
104
91
-
Without durable memory, a later session may only remember: “the payments test was flaky.” It cannot tell whether that conclusion is current or where it came from.
105
+
Without grounded memory, a later session may only remember: “the payments test was
106
+
flaky.” It cannot tell whether that conclusion is current or where it came from. The
107
+
worked example records the initial failure as `claim_11111111`, captures a passing UTC
108
+
rerun, and appends `claim_22222222` with `supersedes: "claim_11111111"`.
92
109
93
110
With GraphKeeper, the active correction remains a flat, reviewable claim:
0 commit comments