Keepwise

Local-first, inspectable memory for Pi coding sessions.

Keepwise is a native Pi extension that gives coding agents durable memory without a hosted service, vector database, or required LLM calls. It stores workspace-scoped facts, lessons, handoffs, plans, decisions, progress, and graph relationships in a local SQLite database.

Status: early v1. The supported and tested integration is the Pi extension runtime. Other agent/editor integrations are not currently implemented.

Purpose

Long coding sessions lose context when a session ends, a branch changes, or an agent is restarted. Keepwise preserves the useful parts of that context in records that are:

• Local — data stays in the workspace by default.
• Inspectable — users can search, review, forget, and clear memory explicitly.
• Deterministic — exact lookup, SQLite FTS5, and substring fallback; no embeddings required.
• Advisory — live instructions, repository state, and fresh tool output always take priority.
• Safety-conscious — secret-like durable text is rejected or redacted before storage or prompt injection.

Features

• Workspace-scoped SQLite storage with migrations and WAL mode
• Facts and reusable lessons
• Session handoffs and /memory-last resume recall
• Deterministic /memory-save consolidation
• Bounded before_agent_start prompt injection
• Plans, tasks, decisions, and progress history
• Directed graph links and depth-limited traversal
• Explicit soft-delete and forget operations
• Secret detection and redaction
• No required network access, hosted account, or LLM
• TypeScript source with an extensive automated test suite

Install/use as a Pi extension

Prerequisites

• Pi installed
• Node.js and npm

Install dependencies

npm install

Load Keepwise in Pi

From the repository directory:

pi -e ./src/index.ts

You can also load the repository as an extension directory through Pi settings:

{
  "extensions": [
    "/absolute/path/to/keepwise"
  ]
}

The package manifest also declares the extension entry point:

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

Compatibility

Keepwise currently implements and tests a native Pi extension. Other agent and editor integrations are future work, not current features.

How it works

Keepwise participates in the Pi lifecycle:

1. session_start — opens or creates the workspace database, runs migrations, initializes FTS5 when available, and creates a session row.
2. before_agent_start — retrieves relevant memory and injects a bounded, clearly marked <memory> block only when useful.
3. agent_end — captures recent session messages for later handoff building.
4. Session switch, fork, and shutdown — performs deterministic consolidation and saves or updates a session handoff.
5. session_shutdown — closes the database cleanly.

The default database path is:

<workspace>/.pi/memory/memory.sqlite

Configuration

Default runtime settings are:

Setting	Default	Purpose
enabled	true	Enable the extension runtime
dbPath	.pi/memory/memory.sqlite	Workspace-relative SQLite path
maxInjectedChars	8000	Maximum injected memory size

These settings are supported through MemoryRuntimeOptions.config; a separate end-user configuration UI is not currently provided.

Memory philosophy

Keepwise favors durable, inspectable, local memory over opaque transcript accumulation. Memory is advisory rather than authoritative, and deterministic retrieval is preferred for the first release.

Memory model

Keepwise stores several related record types:

• Facts — stable project knowledge
• Lessons — reusable corrections and practices
• Sessions — session identity and handoffs
• Plans and tasks — active and historical work
• Decisions — rationale and implementation details
• Progress — milestones and verification evidence
• Graph items and links — relationships between memory records
• Memory events — auditable mutation history

Retrieval follows a deterministic ladder:

1. exact ID or key lookup
2. SQLite FTS5 search when available
3. substring fallback

Injected memory is bounded, advisory, and resume-gated for last-session handoffs. It must never override current instructions or live repository evidence.

Commands

Implemented Pi slash commands include:

/memory [help|status]
/memory-stats
/memory-search <query>
/memory-lessons [query]
/memory-forget <id-or-prefix>
/memory-last
/memory-save [note]
/memory-clear

/plan
/plan list [all]
/plan activate <id>
/plan close <id>
/plan cancel <id> [reason]
/plan next [plan-id-or-prefix]
/plan resume [plan-id-or-prefix]
/plan done <id>
/plan block <id> <reason>
/plan cancel-task <id> [reason]

/decision <summary>
/decision delete <id> [reason]
/progress <status> <description>
/progress delete <id> [reason]

/graph <item-id-or-prefix>
/graph delete-link <id> [reason]
/graph delete-item <type> <id> [reason]

The complete command and tool reference is in docs/COMMANDS_AND_TOOLS.md.

Tools

Keepwise registers tools for:

• memory statistics, search, facts, lessons, and forgetting
• session handoff save/get/recall
• plans and tasks
• decisions and progress
• graph links, neighbors, traces, and deletion

Tool results provide both human-readable content and structured details, making them useful to agents and scripts.

Security and trust model

Keepwise is designed for local development, not as a credential store or transcript archive.

• Stored memory is untrusted advisory state.
• Current instructions and fresh tool output win over remembered content.
• Workspace scope is enforced across implemented reads and writes.
• Secret-like durable text is rejected or redacted depending on the surface.
• Raw transcripts are not the durable storage target.
• /memory-clear requires explicit confirmation before workspace cleanup.

Testing

Install dependencies and run the project checks:

npm install
npm run typecheck
npm test
npm run pack:check

The tests cover migrations, SQLite behavior, workspace isolation, command and tool registration, facts, lessons, handoffs, plans, decisions, progress, graph operations, prompt safety, consolidation, no-network behavior, no-LLM fallback, and package contents.

Repository layout

keepwise/
├── src/
│   ├── commands/       Pi slash commands
│   ├── db/             SQLite schema, migrations, transactions, workspaces
│   ├── decisions/      Decision storage
│   ├── graph/          Graph records and traversal
│   ├── memory/         Facts, lessons, search, safety, injection
│   ├── plans/          Plans and tasks
│   ├── progress/       Progress storage
│   ├── sessions/       Handoffs and session lifecycle
│   ├── tools/          Agent-callable tools and schemas
│   ├── index.ts        Extension entry point
│   └── memory-runtime.ts Runtime coordinator
├── tests/              Automated tests and fixtures
├── docs/               Detailed command/tool reference
├── README.md
├── LICENSE
├── CHANGELOG.md
└── package.json

V1/V2 roadmap

Implemented in v1:

• local SQLite memory
• deterministic retrieval and fallback
• bounded prompt injection
• session handoffs
• plans and tasks
• decisions and progress
• graph links
• explicit memory management commands
• Pi extension loading

Not implemented yet:

• embeddings or vector retrieval
• cloud synchronization
• richer import/export
• advanced graph visualization
• multi-process conflict coordination
• optional LLM-assisted consolidation
• integrations for other agent or editor runtimes

License

Keepwise is licensed under the MIT License.