Imported from ch-arslanahmad/pods (AGENTS.md). Install upstream with npx skills add ch-arslanahmad/pods. Copyright stays with the author.

AGENTS.md, pods repo

Always load karpathy-guidelines first on every session — this is the primary behavioral instruction set.

This file is the single source of truth for repo state and conventions.

Repo Purpose

MCP-native memory server for AI agents. Organize knowledge by project, session, and category.

GitHub: ch-arslanahmad/pods

Current State

Stage 1 — Local. SQLite + FTS5, 8 MCP tools + 1 prompt + REST API. Python (server.py + api.py + db/ package). stdio + HTTP modes.

/
├── server.py              MCP tool definitions, CLI arg parsing
├── api.py                 REST API layer (Starlette routes + OpenAPI spec)
├── tunnel.py              ngrok tunnel management
├── pod                    CLI entry point (Click, 382 lines)
├── pod.pid                process PID file
├── requirements.txt       Python deps (mcp, pydantic, starlette, uvicorn, click)
├── db/
│   ├── database.py        SQLite connection, schema creation
│   ├── db_operations.py   CRUD operations
│   ├── schema.sql         DDL source of truth (FTS5, triggers)
│   ├── seed.json          Seed data for bootstrapping
│   ├── migrate.py         Migration runner
│   ├── migrations/        Versioned migration files
│   └── pods.db            SQLite database (gitignored)
├── tests/
│   ├── conftest.py        pytest fixtures
│   └── test_migrations.py Migration tests
├── PLAN.md                True build plan
├── docs/                  Vision, architecture, gaps, troubleshooting, dev guide
└── .claude/skills/        Repo-local skills

Setup

Install dependencies and verify the server runs:

pip install -r requirements.txt   # mcp is pinned <2.0.0
python3 server.py --help

See docs/troubleshooting.md for install/dependency issues and docs/development.md for running modes and tests.

File Status

[x] = good | [~] = needs work | thin = stub

Conventions

• MCP tool naming: pods_verb (e.g. pods_find, pods_add)
• Schema: SQLite with JSON columns for associations, FTS5 for search
• Soft deletes via deleted_at, never hard delete
• Comments allowed but kept minimal and meaningful — no noise, no obvious self-explanatory code
• Python stdlib + mcp + pydantic + starlette + uvicorn, minimal dependencies
• Pin mcp<2.0.0 — v2 renamed FastMCP to MCPServer, which breaks existing code. Do not upgrade without migrating server.py
• PRs must contain multiple small, meaningful commits — never a single big commit

Skill Activation

Gaps & Fixes

Essential Gaps

Validation

Pydantic works natively with FastMCP. Use Field(min_length=1, max_length=200) on tool params. FastMCP auto-rejects invalid input before DB code runs.

Minor Fixes

• Return format: pods_add returns int, pods_find returns dicts, pods_delete returns bool — inconsistent
• Typo Iidx_pods_category in db/database.py:37 — double i Fixed
• Connection per call — opens+closes on every invocation. Fine at low scale, bad pattern long-term
• Rename create_db() → ensure_schema() in db/db_operations.py:9 — name implies it creates the DB, but it only runs migrations. Misleading.

Code Smells

• Auto-migration on startup (server.py:91 → db.create_db() → migrate.run()) — runs every time the server boots. Fine for single-dev SQLite, but should become an explicit migrate deploy step before multi-instance or prod deployment. Idempotent today, but masks failures silently.

Dead Code

Priority

Feature Ideas

See features.md for proposed features and ideas.

Environment

• Working directory: /home/arslan/Desktop/github/pods
• Platform: Linux
• User: arslan