org-agent-memory

Durable per-project memory and plan tracking for AI coding agents using plain Org mode files.

The package keeps mutable tasks separate from append-only history, supports ordered plans with stable substep IDs, and includes an optional Pi extension for ambient project orientation and structured plan updates.

Features

• One Org file per logical project, independent of the working directory
• Session-scoped project selection for shared folders
• TODO, NEXT, BLOCKED, DONE, and CANCELLED states
• Ordered plans with stable WORK_ID and STEP_ID properties
• Automatic parent progress such as [2/5]
• Append-only task and step history
• Unified capture for journal entries, inbox items, tasks, human notes, plans, and decisions
• Context-aware /cap command with /capture alias and j/J/i/t/n/p/d shortcuts
• Active-model drafts are reviewed before writing; -l/--literal bypasses AI
• Lowercase /cap j appends journal prose; uppercase /cap J appends a same-day scheduled TODO
• Journal entries preserve an existing Org date hierarchy and store project, Pi, and tmux handoff metadata as Org properties
• Atomic writes and process locking on macOS/Linux
• Natural-language agent workflow through the bundled skill
• Structured org_memory tool and /memory command for Pi
• Persistent /org on and /org off toggle for the Pi integration and bundled skill
• No telemetry; only context-aware capture drafting calls the active Pi model provider

Requirements

• Python 3.10 or newer
• macOS or Linux (fcntl is used for file locking)
• Pi is optional; the Python CLI and skill can be used by other agent harnesses

Install with Pi

From GitHub:

pi install git:github.com/<owner>/[email protected]

Try a local checkout without installing it:

pi -e .

After changing an installed local extension, run /reload in Pi.

Install as a standalone skill

Copy skills/org-agent-memory/ into a supported agent skill directory, for example:

cp -R skills/org-agent-memory ~/.agents/skills/

Configuration

Memory files use the first available location:

1. ORG_AGENT_MEMORY_DIR
2. legacy ORG_WORKLOG_DIR
3. memoryDirectory in ~/.config/org-agent-memory/config.json
4. $XDG_DATA_HOME/org-agent-memory
5. ~/.local/share/org-agent-memory

Example:

{
  "memoryDirectory": "~/Documents/org/agent-worklogs",
  "journalFile": "~/Documents/org/journal.org",
  "enabled": true
}

enabled defaults to true for backward compatibility. Pi users can persistently change it with /org on or /org off; the command reloads Pi resources immediately. journalFile is required for /cap j and /cap J unless ORG_AGENT_MEMORY_JOURNAL is set. Journal writes preserve or create the existing year/month/day hierarchy: lowercase j writes timestamped prose under Logs, while uppercase J writes a TODO under Tasks with SCHEDULED set to that day. Both use locking plus atomic replacement.

Optional environment variables:

| Variable | Purpose | |---|---| | ORG_AGENT_MEMORY_DIR | Directory containing project Org files | | ORG_AGENT_MEMORY_JOURNAL | Journal Org file; overrides journalFile | | ORG_AGENT_MEMORY_CONFIG | Alternate configuration file | | ORG_AGENT_MEMORY_PROJECT | Default logical project | | ORG_AGENT_MEMORY_SESSION | Session identity outside Pi | | ORG_AGENT_MEMORY_STATE_DIR | Session-selection state directory | | ORG_AGENT_MEMORY_SCRIPT | Python helper override for the Pi extension |

Project selection

Project identity is independent of the current folder. Selection precedence is:

1. explicit --project;
2. session selection;
3. environment configuration;
4. Git repository;
5. folder fallback.

The first four sources are high confidence. Folder fallback is intentionally low confidence and is not presented as a confirmed project. When unresolved, orient compares the request with known project slugs, normalized project-name tokens, active task titles, and projects previously used from the same folder. It persists only a unique high-confidence match.

python3 skills/org-agent-memory/scripts/memory.py orient \
  "Implement the org-agent-memory project selection fix"
python3 skills/org-agent-memory/scripts/memory.py current-project

If classification is wrong, correct the session and optionally move the task with its complete history:

python3 skills/org-agent-memory/scripts/memory.py correct-project org-agent-memory
python3 skills/org-agent-memory/scripts/memory.py \
  correct-project org-agent-memory --move <task-id>

Use --project <source> before correct-project when the task is in a source project other than the current session selection.

Usage

The intended interface is natural language. Agents should orient automatically, ask about project choice only when genuinely ambiguous, and update memory only for meaningful work.

Pi slash captures are context-aware by default. Arguments are focus instructions, not literal content. The active Pi model drafts one structured capture from up to 20,000 recent characters of user/assistant text; hidden reasoning and tool results are excluded. Every AI draft opens type-specific review/edit dialogs before writing.

/cap j                              # Review the last assistant reply verbatim
/cap j summarize the decisions      # AI-draft journal prose with this focus
/cap J identify the next action      # AI-draft today's journal TODO
/cap t create a follow-up task       # AI-draft task title/details
/cap n capture the findings          # AI-draft note title/body
/cap p turn this into a plan          # AI-draft title/context/ordered steps
/cap d record the chosen approach    # AI-draft decision/context/rationale
/cap t -l Fix tests                  # Literal short form; no model request
/cap i --literal Exact inbox text    # Literal long form; no model request

/cap j without an instruction is the cheap exception: it takes the last assistant reply verbatim and opens the editor without another model request. Other non-literal captures require conversation text, an active authenticated model, and interactive review. Use -l or --literal in headless modes. /cap with no type opens the type selector.

The Python CLI remains literal and never invokes a model. Direct CLI examples:

MEMORY=skills/org-agent-memory/scripts/memory.py

python3 "$MEMORY" use sre-as-agent
python3 "$MEMORY" current-project
python3 "$MEMORY" projects --tasks

python3 "$MEMORY" --session <pi-session-id> cap j "Journal entry"
python3 "$MEMORY" cap J "Write release notes"
python3 "$MEMORY" cap inbox "Think about agent observability"
python3 "$MEMORY" cap task "Fix authentication tests"
python3 "$MEMORY" cap note "Token storage" --body "Never use localStorage" --tag security
python3 "$MEMORY" cap decision "Use PostgreSQL" --body "Use PostgreSQL for shared memory"
python3 "$MEMORY" cap plan "Ship authentication" \
  --step "Analyze" --step "Implement" --step "Verify"
python3 "$MEMORY" cap list

python3 "$MEMORY" plan "Ship authentication" \
  --step "Analyze current flow" \
  --step "Implement validation" \
  --step "Verify deployment"

python3 "$MEMORY" steps "Ship authentication"
python3 "$MEMORY" step start "Ship authentication" next
python3 "$MEMORY" step complete "Ship authentication" analyze-current-flow \
  --verification "Flow documented"

Run python3 skills/org-agent-memory/scripts/memory.py --help for all commands.

Org structure

#+TODO: TODO NEXT BLOCKED | DONE CANCELLED

* Inbox

* Tasks
** NEXT Ship authentication [1/3]
:PROPERTIES:
:WORK_ID: 5e9...
:ORDERED: t
:END:

*** DONE Analyze current flow
:PROPERTIES:
:STEP_ID: analyze-current-flow
:END:

*** NEXT Implement validation
:PROPERTIES:
:STEP_ID: implement-validation
:END:

*** TODO Verify deployment
:PROPERTIES:
:STEP_ID: verify-deployment
:END:

* Human Notes
** Token storage :security:
:PROPERTIES:
:CAPTURE_ID: 8ec431ab...
:CAPTURE_TYPE: note
:AUTHOR: human
:END:

Never store refresh tokens in localStorage.

* Decisions

* Archived Captures

* Log
** 2026-07-26
*** 18:30 step-completed — Ship authentication / Analyze current flow
:PROPERTIES:
:WORK_ID: 5e9...
:STEP_ID: analyze-current-flow
:END:

Pi integration

The extension registers:

• /org on and /org off to toggle the integration;
• the structured org_memory tool;
• /cap j for timestamped journal prose with resumable Pi and tmux metadata;
• /cap J for a same-day scheduled TODO under the journal's Tasks section;
• /cap for fast or interactive project capture and /capture as its alias;
• /memory for project and active-task inspection;
• session startup restoration;
• bounded memory context before agent runs;
• a compact status line and active-task widget.

The toggle is global and stored as enabled in the existing configuration file. When off, the small /org bootstrap and journal-only /cap j and /cap J routes remain registered; project captures, /capture, the tool, other commands, hooks, UI, context injection, and bundled skill are absent after the automatic reload. Context-aware journal drafting can still use the active Pi model; -l/--literal never invokes it. Journal prose entries store the full pi --session <id> command in PI_RESUME. When Pi is running inside tmux, TMUX_RESUME stores tmux at -t<session>. When memory is on and a high-confidence project memory file exists, PROJECT_MEMORY stores its relative Org link. Independently installed skill copies and skills supplied explicitly with --skill are separate Pi resources and are not controlled by this package toggle.

Hooks provide awareness and UI only. Plan creation and state changes happen through explicit structured tool calls; the extension does not scrape prose or infer completion from a successful command.

Privacy and security

Generated memory and journal entries can contain local paths, private repository names, branch names, commit hashes, session IDs, and user-authored text. Keep them outside this repository and review them before sharing.

Context-aware /cap sends bounded recent conversation text and the focus instruction to the active Pi model provider, which may incur provider usage costs. Pi resolves authentication in memory; this package does not store or log credentials. Use -l/--literal to avoid a model request. The Python scripts make no network requests, and the package includes no telemetry. As with every Pi extension, installing the package grants it the permissions of the Pi process. Review third-party code before installation.

See SECURITY.md.

Development

python3 -m py_compile skills/org-agent-memory/scripts/*.py
python3 -m unittest discover -s tests -v
pi -e . --list-models
npm pack --dry-run

License

MIT