Memory Skill

Local-first memory layer for assistant and coding workflows.

中文说明

This project provides:

• a Python memory engine under skills/memory/
• a distributable Codex skill under memory-skill/
• a packaging script that builds a .skill archive from the latest source without duplicating runtime code in the repo

Features

• Separate global, project, and session storage
• Durable memory types for preference, profile, correction, goal, decision, lesson, and fact
• Workflow commands:
  • prepare-context for pre-response recall
  • capture-outcome for post-task memory extraction
• Manual commands:
  • store, search, learn, prune, export, import, list-projects
• SQLite persistence plus JSON session state
• Keyword search with deterministic local embedding fallback
• Stable JSON output for both CLI and handler integration

Repository Layout

memory-skill/   Codex skill source and runtime wrapper
skills/memory/  Python implementation
tests/memory/   unit tests
tools/          packaging utilities

Installation

python -m pip install -e .

Available entrypoints:

memory-skill ...
python -m skills.memory ...
python -m skills.memory.memory_cli ...

Quick Start

Store and search durable memory:

memory-skill store "User prefers concise answers" --type preference --scope global
memory-skill search "concise answers" --scope global

Use the workflow interface:

memory-skill prepare-context "draft a status update"
memory-skill capture-outcome --messages "[{\"role\":\"user\",\"content\":\"Please use concise answers.\"}]"

Project-scoped usage:

memory-skill prepare-context "fix sqlite config issues" --project-path E:\work\demo
memory-skill learn "stabilize config loading" "Always validate environment files before parsing." --project-path E:\work\demo

Python API

Main exports live in skills/memory/__init__.py.

from skills.memory import prepare_context, capture_outcome, store_memory

context = prepare_context("draft a status update")

outcome = capture_outcome(
    messages=[{"role": "user", "content": "Please use concise answers."}]
)

stored = store_memory(
    content="User prefers concise answers.",
    scope="global",
    type="preference",
)

Handler example:

from skills.memory import handle_memory_request

response = handle_memory_request(
    {
        "command": "prepare_context",
        "payload": {
            "query": "draft a status update",
        },
    }
)

Storage

By default runtime data is stored under:

skills/memory/data/
  global.db
  projects.db
  project/<project_hash>.db
  session/<session_id>.json

Override with MEMORY_SKILL_DATA_ROOT when needed.

Development

Run tests:

python -m unittest discover -s tests\memory -p "test_*.py" -v

Build the distributable skill:

python tools/package_skill.py

This writes release/memory-skill.skill.

Notes

• Project databases are derived from sha1(normalized_project_path)
• Imports reuse the normal store path, so dedupe still applies
• capture-outcome only auto-stores high-confidence user long-term memory by default
• The current embedding fallback is deterministic and local by design