GPTkms

GPTkms is a local-first Knowledge Management System for Codex and ChatGPT Work.

It follows a simple idea:

• keep durable knowledge in plain markdown
• expose that knowledge through an MCP server
• separate project memory from global memory
• use skills to teach retrieval and promotion workflows

The project is inspired by the LLM Wiki direction from Andrej Karpathy and the implementation ideas documented in thClaws.

Why this exists

Most AI workflows forget too much and over-rely on raw conversation history.

GPTkms tries to solve that by treating long-term memory as a maintained knowledge base instead of a pile of transcripts. The goal is to make memory:

• inspectable
• editable
• portable
• cross-project
• compatible with Codex workflows

Positioning

GPTkms sits between simple persistent-memory tools and full personal knowledge systems.

In practical terms:

• it is more structured and curated than a flat memory layer
• it is more operational and agent-facing than a second-brain app like Obsidian
• it is built from Codex-native primitives such as MCP and skills, rather than replacing them

For the longer comparison, see docs/POSITIONING_AND_LANDSCAPE.md.

Current status

This repository is an early working prototype.

Already implemented:

• file-backed markdown KMS layout
• MCP stdio server
• global and project scopes
• search, read, write, ingest, promotion, lint, and conflict tools
• two Codex workflow skills
• Playwright-based browser automation scaffold
• browser-facing KMS demo page
• sample KMS content for testing

Still in progress:

• plugin packaging
• merge/update flow for existing global pages
• stronger conflict detection
• broader multi-project examples

Core ideas

1. Markdown is the durable memory layer

Compiled knowledge lives in pages/.

Raw evidence lives in raw/.

This keeps memory readable by both humans and agents.

2. MCP is the runtime integration point

The MCP server gives Codex and ChatGPT a structured way to search, read, update, and promote memory.

3. Memory has scope

• global/ is for reusable cross-project knowledge
• projects/<project-id>/ is for repo-specific knowledge

4. Promotion should be curated

Project knowledge should not automatically become global knowledge.

Repository layout

.
├── .codex/
│   ├── kms.json
│   └── skills/
├── .github/
│   └── workflows/
├── docs/
├── sample_kms/
├── scripts/
└── src/

Included components

• docs/kms-schema-and-mcp-spec.md: implementation-oriented schema and tool contract
• docs/INSTALLATION.md: installation and local run guide
• docs/BROWSER_AUTOMATION.md: Playwright and Chromium setup for repo-local browser automation
• docs/ORIGIN_AND_DIRECTION.md: project background and design direction
• docs/POSITIONING_AND_LANDSCAPE.md: how GPTkms differs from adjacent memory approaches
• docs/PUBLISHING_CHECKLIST.md: final steps for creating the GitHub repo and publishing
• docs/RELEASE_ROADMAP.md: proposed release path
• sample_kms: sample knowledge base for smoke tests
• src/gptkms_mcp/server.py: MCP protocol and tool dispatch
• src/gptkms_mcp/kms_store.py: file-backed storage and quality checks
• .codex/skills/kms-answer-from-wiki: retrieval-first workflow skill
• .codex/skills/kms-promote-session-insights: promotion workflow skill
• .codex/skills/kms-save-session-to-kms: workflow skill for preserving the current session into project KMS
• demo/index.html: static browser demo for KMS-shaped content
• tests/browser-smoke.mjs: browser automation smoke test using Playwright

Implemented MCP tools

• kms_list_bases
• kms_get_active_context
• kms_search
• kms_read_page
• kms_create_page
• kms_update_page
• kms_append_log
• kms_ingest_source
• kms_promote_candidate
• kms_build_context_pack
• kms_lint_links
• kms_find_conflicts

Quick start

Use the bundled Codex Python runtime:

& 'C:\Users\sc282\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' `
  'E:\My Projects\GPTkms\scripts\smoke_test.py'

Then run the MCP server:

& 'C:\Users\sc282\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' `
  'E:\My Projects\GPTkms\scripts\run_server.py'

For a fuller setup guide, see docs/INSTALLATION.md.

Browser automation

This repo now includes a small Playwright scaffold for browser automation.

Quick commands:

npm install
npm run browser:install
npm run browser:smoke
npm run browser:demo

If node is not on PATH in Codex, use:

powershell -ExecutionPolicy Bypass -File .\scripts\run_browser_smoke.ps1

For details, see docs/BROWSER_AUTOMATION.md.

Demo

The repository includes a small browser-facing demo at demo/index.html.

It shows:

• KMS-style entries with scope and citations
• client-side search over project and global memory
• a simple UI flow that Playwright can validate

Example Codex MCP config

[mcp_servers.gptkms]
command = "python"
args = ["E:\\My Projects\\GPTkms\\scripts\\run_server.py"]

[mcp_servers.gptkms.env]
GPTKMS_ROOT = "E:\\My Projects\\GPTkms\\sample_kms"
GPTKMS_PROJECT_DIR = "E:\\My Projects\\GPTkms"

Validation

Useful local checks:

python -m py_compile src/gptkms_mcp/server.py src/gptkms_mcp/kms_store.py scripts/smoke_test.py
python scripts/smoke_test.py
python scripts/validate_repo.py
npm run browser:smoke
npm run browser:demo

Saving session knowledge

To preserve the current work into project memory:

1. save a raw session summary
2. update durable project pages
3. promote only reusable knowledge into global memory

You can use scripts/save_session_to_kms.py to create the raw session source quickly.

In Codex environments without node on PATH, replace the last command with:

powershell -ExecutionPolicy Bypass -File .\scripts\run_browser_smoke.ps1

Roadmap

Short version:

• improve merge/update workflows for global pages
• package the MCP server and skills as a reusable plugin
• test against more than one real project
• stabilize the public tool contract

For the fuller release plan, see docs/RELEASE_ROADMAP.md.

Contributing

See CONTRIBUTING.md.

License

MIT