verimemo

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

Verified local Markdown memory for Codex Desktop, Codex CLI, and ChatGPT Desktop.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Verified, project-scoped memory for Codex. 
 Readable on disk. Recalled across tasks. Repairable when reality changes.

<a href="#install">Install</a> ·
 <a href="docs/PRIVACY.md">Privacy</a> ·
 <a href="docs/TROUBLESHOOTING.md">Troubleshooting</a> ·
 <a href="CONTRIBUTING.md">Contributing</a>

---

## Install

```powershell
npx verimemo
```

VeriMemo supports Windows 10/11 and requires Node.js 20 or newer.
It works with Codex Desktop, Codex CLI, and Codex tasks in ChatGPT Desktop.

One guided setup verifies Codex access and configures:

- a recommended multilingual semantic + exact FTS5 mode;
- a lightweight FTS5-only mode; or
- a custom local Sentence Transformers model.

VeriMemo then creates its isolated Python runtime, managed storage, hidden
Windows hooks, background semantic service, and user-level `verimemo` command.
Installation and updates are transactional.

For unattended installation with recommended settings:

```powershell
npx verimemo --yes
```

Open a new Codex task after installation so the plugin hooks are loaded.

## Stop rebuilding context from scratch

VeriMemo gives Codex a durable understanding of the project—not just a larger
chat history. Decisions, constraints, fixes, verification results, and open work
follow the project into the next task automatically.

| Remember across tasks | Inspect everything | Correct the record |
|---|---|---|
| Start a new Codex task without repeating the architecture, recent work, or why a decision was made. | Durable memory is readable local Markdown with source, confidence, freshness, and lifecycle metadata. | Corrections supersede stale facts; lint, conflict detection, and reconciliation keep memory coherent. |

No dashboard, hosted vector database, or manual storage setup is required.
Recall and end-of-turn capture happen automatically.

## How it works

1. A Codex hook captures the important handoff from the current task.
2. GPT-5.6 Luna extracts durable knowledge through the signed-in Codex client;
   writes are staged, validated, and committed atomically.
3. A new task receives pending context immediately, then relevant durable
   Markdown with provenance and freshness metadata.
4. Corrections replace stale facts instead of accumulating contradictions.

Reader and writer budgets are independent: recall places query-ranked answers
before bounded pending/NOW auxiliaries, while Luna receives a smaller
single-copy writer context. Safe exact duplicates can be rejected locally with
zero writer tokens. Reader recall progressively selects a 480-token exact,
900-token clear, or 1,800-token causal/ambiguous budget under the 2,500-token
safety ceiling. Paths, filenames, memory IDs, symbols, versions, error codes,
and config keys have a dedicated exact lane; managed facts are indexed
atomically, and a Decision expands to its causal parent only for why/risk/
consequence queries. Routine writes use the compact `routine_delta` protocol
and automatically escalate to `causal_maintenance` when needed.

## Supported clients

| Client | Shared project memory | Support level |
|---|---:|---|
| Codex Desktop | Yes | Automated + release smoke coverage |
| Codex CLI | Yes | Automated + release smoke coverage |
| ChatGPT Desktop · Codex tasks | Yes | Same plugin runtime + manual release check |

All three clients resolve the same project identity and managed Markdown store
on Windows.

## Local, managed storage

Setup chooses the standard Windows data directory automatically:

```text
%LOCALAPPDATA%\VeriMemo
```

Canonical Markdown lives under `memory\Projects`. Private indexes, queues,
logs, tokens, and model state live separately under `state` and are never
committed with project source.

The memory stays readable in any Markdown editor, including Obsidian.

```powershell
verimemo storage path
verimemo storage open
verimemo storage move "D:\Private Data\VeriMemo Memory"
```

`storage move` pauses active writes, copies only managed Markdown, verifies each
file by SHA-256, atomically switches configuration, and removes the old managed
subtree only after a successful cut-over.

## Everyday control

| Command | Purpose |
|---|---|
| `verimemo doctor` | Diagnose installation, hooks, writer, service, and storage |
| `verimemo status` | Show queue, index, conflict, and freshness health |
| `verimemo search "query"` | Inspect what recall can find |
| `verimemo lint --reconcile` | Audit and repair Markdown, ledger, index, and lifecycle drift |
| `verimemo remember "fact" --wait` | Explicitly persist important project knowledge |
| `verimemo storage open` | Open the readable Markdown memory |
| `verimemo update` | Transactionally update the installation |

Normal uninstall preserves Markdown memory:

```powershell
verimemo uninstall
```

Deleting managed memory requires an explicit destructive flag:

```powershell
verimemo uninstall --purge-data
```

## Trust boundaries

- Markdown memory, SQLite indexes, queues, logs, and optional Hugging Face
  embeddings stay local.
- Bounded task excerpts are sent through the signed-in Codex client to GPT-5.6
  Luna for memory extraction and use the user's Codex quota.
- The model chosen during setup is the local retrieval model; Luna remains the
  verified writer model.
- Redaction runs before persistence, post-model DLP runs before commit, service
  tokens are isolated, and recalled Markdown is treated as untrusted context.
- VeriMemo has no analytics or telemetry endpoint of its own.

Read the complete [privacy and data-flow statement](docs/PRIVACY.md).

<details>
<summary>Engineering details</summary>

### Reliability model

- Durable per-project queues with renewable leases and fencing tokens
- A bounded pending handoff for important uncommitted work
- Staged plans, conditional multi-file commits, rollback, and crash recovery
- Lifecycle-aware Decisions with provenance and freshness review
- Incremental conflict detection and deterministic reconciliation
- Stable-ID/Bayesian recall-usefulness feedback with correction resets
- Truncation-aware session continuation instead of permanently hidden tails
- Persistent HNSW retrieval for large vaults with exact small-vault fallback

### Development

```powershell
python -m pip install -r requirements-dev.txt
python -m ruff check plugins/verimemo
python -m pytest -q plugins/verimemo/tests
npm test
npm run test:e2e
npm run pack:audit
```

Repository layout:

- `plugins/verimemo/` — plugin runtime, bundled skill, and Python tests
- `installer/` and `bin/` — dependency-free npm bootstrap and CLI
- `.agents/plugins/marketplace.json` — Codex marketplace manifest
- `docs/` — privacy, troubleshooting, methodology, and visual assets

Release checks inspect `npm pack --dry-run --json`; tests, caches, memory,
runtime databases, credentials, and local configuration stay outside the package.

</details>

## License and security

VeriMemo is licensed under [Apache-2.0](LICENSE). Report vulnerabilities using
the private process in [SECURITY.md](SECURITY.md); contribution rules live in
[CONTRIBUTING.md](CONTRIBUTING.md).

VeriMemo · local memory with a paper trail

verimemo

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README