https://github.com/rogerchappel/contextloom
Local-first context manager for lossless agent transcripts with cited chunks
https://github.com/rogerchappel/contextloom
agent-context agent-tools cli local-first retrieval transcripts typescript
Last synced: 9 days ago
JSON representation
Local-first context manager for lossless agent transcripts with cited chunks
- Host: GitHub
- URL: https://github.com/rogerchappel/contextloom
- Owner: rogerchappel
- License: mit
- Created: 2026-05-03T20:43:40.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-05T21:31:18.000Z (29 days ago)
- Last Synced: 2026-05-05T23:25:27.143Z (29 days ago)
- Topics: agent-context, agent-tools, cli, local-first, retrieval, transcripts, typescript
- Language: TypeScript
- Homepage: https://github.com/rogerchappel/contextloom
- Size: 42 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# contextloom
A local-first context manager for agent sessions. It turns transcripts, notes, and tool traces into a deterministic manifest of retrievable chunks with citations back to exact files, line ranges, byte offsets, and hashes.
Think of it as a small loom for long context: feed it local files, get back a plain JSON index another agent, CLI, or editor plugin can trust.
## Why
Agent work often lives in long chat logs and noisy tool output. Summaries are useful, but they can lose the exact quote that proves a decision. `contextloom` keeps the original thread recoverable while making chunks easy to search and cite.
## Install
```sh
npm install
npm run build
```
For local CLI use while developing:
```sh
node dist/src/cli.js --help
```
When installed from npm in the future, the binary name is `contextloom`.
## Quickstart
```sh
npm run build
node dist/src/cli.js inspect fixtures/sample --output out/sample
node dist/src/cli.js search out/sample/manifest.json "deployment decision"
node dist/src/cli.js show out/sample/manifest.json chunk-0001
node dist/src/cli.js verify out/sample/manifest.json
```
`inspect` writes:
- `manifest.json` — machine-readable chunks, citations, hashes, and stats.
- `manifest.md` — a human skim table.
## CLI
```text
contextloom inspect [--output out/context] [--format json|markdown]
contextloom search [--limit 5] [--format json|markdown]
contextloom show [--format json|markdown]
contextloom verify [--format json|markdown]
```
Supported local input formats in the MVP:
- `.jsonl` transcript/event rows with `role`, `content`/`text`/`message`, and optional `timestamp`.
- `.json` arrays or objects containing `messages`, `turns`, `events`, or `transcript`.
- `.md`, `.markdown`, and `.txt` notes/logs.
## Library API
```ts
import { inspect, searchManifest, verifyManifest } from 'contextloom';
const manifest = await inspect({ input: 'fixtures/sample', output: 'out/sample' });
const results = searchManifest(manifest, 'deployment decision', 3);
const verified = await verifyManifest(manifest);
```
## Safety boundaries
`contextloom` is intentionally boring and local-first:
- Reads only files or directories you explicitly pass in.
- Writes only the output directory you request.
- Performs no telemetry, network calls, scraping, publishing, or credential access.
- Uses deterministic chunk ids and source hashes so generated manifests are easy to diff.
Do not point it at private transcripts unless you are comfortable with the output manifest containing excerpts from those files.
## Source attribution
This is an original implementation inspired by the product idea described in `docs/PRD.md`, which mentions the adjacent `lossless-claw` repository as inspiration. This project does not copy that name or implementation; it focuses on a tiny deterministic TypeScript CLI/library MVP.
## Verify
```sh
npm test
npm run check
npm run build
npm run smoke
bash scripts/validate.sh
```
## Examples
See [`examples/basic-usage.md`](examples/basic-usage.md), [`examples/library-api.ts`](examples/library-api.ts), and [`fixtures/sample`](fixtures/sample) for a small agent handoff workflow.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Keep changes local-first, small, tested, and clear about safety implications.
## Security
See [SECURITY.md](SECURITY.md). Please do not put private transcript excerpts or exploit details in public issues.
## License
MIT