ephemeris
Silent session wiki for Claude Code. Captures every session automatically, distills it into a local markdown knowledge base, and lets you query it later.
Ephemeris is a Claude Code plugin that listens for session lifecycle events, stages the raw transcript, and incrementally builds a structured wiki of the decisions, entities, and topics that emerged from your work. Queries run against the wiki with citation-grounded answers — the model is explicitly forbidden from answering outside what the wiki contains.
ephemeris runs entirely inside your active Claude Code session. No API key. No outbound network. All model work is performed by the session's own tool palette.
Zero configuration for the default path. Opt-in scoping and schema customization for power users.
How it works (v0.4.0)
~/.claude/projects/<encoded-cwd>/<id>.jsonl ← native Claude Code transcripts
│
│ /ephemeris:ingest
▼
┌────────────────────────────┐
│ Source readers │
│ - native-transcript │
│ - session-docs (opt-in) │
│ - arbitrary-md (paths) │
└─────────────┬──────────────┘
│
▼
┌──────────────┐
│ wiki │
│ (markdown) │
└──────┬───────┘
│
│ /ephemeris:query
▼
┌──────────────┐
│ grounded │
│ answer + │
│ citations │
└──────────────┘
- Sources —
/ephemeris:ingest reads from one or more configured sources. The default config enables only native-claude-projects, which scans the JSONL transcripts Claude Code already writes to ~/.claude/projects/. No staging copies, no hooks required. Power users can add session-docs or arbitrary-md sources via ~/.claude/ephemeris/config.json.
- Cursor —
~/.claude/ephemeris/cursor.json records the last-seen mtime per locator so subsequent ingests are incremental.
- Citation dedup — every wiki page has a
## Sessions block; appending uses a stable [YYYY-MM-DD <kind>:<id>] key, so re-running ingest never duplicates citations.
- Query —
/ephemeris:query "<question>" runs retrieval over the wiki and returns an answer with an explicit ## Sources block grounded entirely in captured content.
Migration from v0.1.x–v0.3.x: the SessionEnd / PreCompact hooks are now no-ops. To replay backlog from prior installs run python scripts/backfill.py --legacy-staging --with-cursor-init.
Installation
Install via the Claude Code plugin marketplace:
/plugin marketplace add TrevorEdris/ephemeris
/plugin install ephemeris
That is the only required configuration. First hook fire creates the staging and wiki directories and bootstraps the default schema copy.
Commands
| Command | Purpose |
|---|
/ephemeris:ingest | Process every pending staged session (SPEC-010) |
/ephemeris:ingest <session-id> | Process one specific session (SPEC-010) |
/ephemeris:query "<question>" | Ask the wiki a question; returns grounded answer + citations (SPEC-011) |
Configuration
Ephemeris reads from well-known paths under ~/.claude/ephemeris/ and honors a small set of environment overrides.
Multi-source config (~/.claude/ephemeris/config.json)
The default config is bootstrapped on first run. It enables only the universal native-transcript source:
{
"version": 1,
"wiki_root": "~/.claude/ephemeris/wiki",
"cursor_path": "~/.claude/ephemeris/cursor.json",
"sources": [
{
"id": "native-claude-projects",
"kind": "native-transcript",
"root": "~/.claude/projects/",
"scope": {
"exclude": ["~/.claude/**", "**/ephemeris/**"]
},
"filter_title_gen": true
}
]
}
Add a session-docs source to ingest your own dated session-doc tree:
{
"id": "my-session-docs",
"kind": "session-docs",
"root": "~/path/to/your/session-docs",
"dir_pattern": "^(\\d{4}-\\d{2}-\\d{2})[_-](.+)$",
"extractors": {
"SESSION.md": { "sections": ["Goal", "Decisions", "Status"] },
"DISCOVERY.md": { "sections": ["Findings", "Gaps", "Open questions"] },
"PLAN.md": { "sections": ["Target files", "Steps", "Risks", "Verification"] }
}
}
The plugin ships no built-in heading patterns — extractors is opt-in. With no patterns the source still works in pass-through mode (raw markdown handed to the model).
Scope (cwd glob filtering for native-transcript)
TrevorEdris
