Skip to main content
Polpo has two persistent knowledge stores: project memory for your agents and system context for Polpo itself.

​
What is Project Memory?

Project memory is a markdown file (.polpo/memory.md) that Polpo injects into every agent’s context. It’s persistent across sessions and shared by all agents working on your project. Use it to capture:
  • Architecture decisions and patterns
  • Build commands and common operations
  • Known issues and workarounds
  • Coding style and conventions
  • Project-specific knowledge

​
Creating Memory

​
Via TUI

/memory
If no memory file exists, the TUI offers to create one from a template.

​
Via Web UI

Navigate to Memory in the sidebar. Click Create Memory to start from a template.

​
Via API

curl -X PUT http://localhost:3000/api/v1/projects/my-project/memory \
  -H "Content-Type: application/json" \
  -d '{"content": "# Project Memory\n\n## Build\n./node_modules/.bin/tsc"}'

​
Manually

Create .polpo/memory.md in your project root: 
# Project Memory

## Build
- Run `./node_modules/.bin/tsc` to compile (not `npx tsc`)
- Run `npm test` to verify

## Architecture
- Express + SQLite backend
- React 18 frontend with shadcn/ui
- All API routes in src/routes/

## Patterns
- Use Zod for input validation
- Return errors as { ok: false, error: string, code: string }
- Database queries go through src/db.ts

## Known Issues
- SQLite busy_timeout must be >= 5000 for concurrent writes

​
Template

When creating memory through the TUI or web UI, you get a starter template: 
# Project Memory

## Overview
Brief project description.

## Build & Run
- Build: `command here`
- Test: `command here`
- Dev: `command here`

## Architecture
Key architectural decisions and patterns.

## Conventions
Coding conventions and style guides.

## Known Issues
Current issues and workarounds.

​
How Agents Use Memory

When an agent is spawned for a task, Polpo:
  1. Reads .polpo/memory.md
  2. Prepends it to the agent’s system prompt
  3. The agent sees it as project context alongside the task description
This means every agent automatically knows about your build process, patterns, and conventions.

​
Best Practices

  1. Keep it concise — agents have limited context. Focus on actionable info, not prose.
  2. Update frequently — add new learnings as agents discover them. Memory evolves with the project.
  3. Be specific — “Use ./node_modules/.bin/tsc” is better than “use the TypeScript compiler”
  4. Include commands — exact build, test, and lint commands save agent time
  5. Document patterns — if you have a preferred error handling pattern, put it here
  6. Note known issues — prevents agents from rediscovering the same problems
Memory is also available via the React SDK’s useMemory() hook, which provides real-time content with save/reset functionality.

​
System Context

System context (.polpo/system-context.md) is a separate file that stores standing instructions for Polpo itself — not for the agents it spawns. Every time you start a conversation with Polpo (via TUI or the /v1/chat/completions endpoint), this file is injected into Polpo’s system prompt. Use it for:
  • Standing instructions (“always use TypeScript strict mode”)
  • Project conventions Polpo should follow when generating missions
  • Preferences for agent selection or model choice
  • Anything you’d tell a project manager on day one

​
How It Works

  1. Polpo reads .polpo/system-context.md at the start of every conversation
  2. The content is injected as “Standing instructions” in Polpo’s system prompt
  3. Polpo follows these instructions when planning, delegating, and reviewing work

​
Creating System Context

Tell Polpo to remember something during a conversation: 
> Remember: always run npm test after any code change
Polpo uses its append_system_context tool to write this to .polpo/system-context.md. You can also create or edit the file manually.

​
Memory vs System Context

Project MemorySystem Context
File.polpo/memory.md.polpo/system-context.md
Injected intoAgent promptsPolpo’s own prompt
PurposeProject knowledge for agentsStanding instructions for Polpo
Who uses itThe worker agentsPolpo (the manager)
Managed via/memory command, API, or manual editappend_system_context tool, or manual edit