agentram 0.1.0

package/README.md

@@ -0,0 +1,729 @@
+# AgentRAM
+
+Async, model-agnostic Working RAM for coding agents such as Codex, Claude Code, Cursor, and custom MCP clients.
+
+AgentRAM lets the main coding agent keep solving while a memory layer records events, decisions, file activity, task state, and long-running goals into a small project-local RAM store.
+
+## Why
+
+Coding agents can lose direction after long sessions, compact, restart, or model switch. AgentRAM keeps durable context outside the model session:
+
+- Source-of-truth event log.
+- Structured RAM notes.
+- Goal Stack to reduce goal drift.
+- MCP tools any compatible coding agent can call.
+- Swappable memory adapters: heuristic, Ollama, OpenAI-compatible APIs, Anthropic Claude API.
+
+## Quick Start
+
+Install from local clone:
+
+```bash
+git clone https://github.com/trancongnghia/AGENT_RAM.git
+cd RAMofagent
+pip install -e .
+python -m pytest -q
+```
+
+Install from GitHub directly:
+
+```bash
+pip install git+https://github.com/trancongnghia/AGENT_RAM.git
+```
+
+Run MCP server inside any project you want to give memory:
+
+```bash
+cd C:/path/to/your/project
+agentram-mcp
+```
+
+AgentRAM creates project-local storage automatically:
+
+```text
+.agentram/
+  events.jsonl
+  memory.json
+  goal_state.json
+```
+
+No `--ram-root` required. Use `--ram-root` only when you want memory outside the project or shared across projects.
+
+If using the Claude plugin, `.mcp.json` sets `AGENTRAM_AUTO_INIT=true`, so these files are created when MCP starts. You can also call `agentram_init` manually.
+
+## Terminal UI CLI
+
+AgentRAM also includes a dependency-free terminal UI with a Claude Code-like chat frame and button menu:
+
+```bash
+agentram
+```
+
+Equivalent explicit command:
+
+```bash
+agentram tui
+```
+
+Buttons inside the UI:
+
+```text
+[1] Init RAM        [2] Status          [3] Retrieve
+[4] Goal Show       [5] Goal Set        [6] Drift Check
+[7] Events          [8] Replay          [9] Help       [0] Exit
+```
+
+Useful non-interactive commands:
+
+```bash
+agentram init
+agentram status
+agentram goal
+agentram retrieve "adapter Groq memory writer"
+agentram drift "Refactor MCP server"
+agentram replay
+```
+
+Use another RAM folder when needed:
+
+```bash
+agentram --ram-root C:/path/to/project/.agentram status
+```
+
+## npm / npx Usage
+
+AgentRAM can also run through npm. Node only launches the Python package; Python 3.10+ must still be installed.
+
+After the package is published to npm:
+
+```bash
+npm install -g agentram
+agentram status
+agentram tui
+agentram-mcp
+```
+
+Run without global install:
+
+```bash
+npx agentram status
+npx agentram tui
+npx agentram retrieve "adapter Groq memory writer"
+```
+
+Run directly from GitHub before npm publish:
+
+```bash
+npx github:trancongnghia/AGENT_RAM status
+npx github:trancongnghia/AGENT_RAM tui
+```
+
+Run from local clone:
+
+```bash
+npm install
+npm run agentram -- status
+npm run agentram -- tui
+npm run agentram:mcp
+```
+
+Publish to npm:
+
+```bash
+npm login
+npm publish --access public
+```
+
+Use with Claude/Codex MCP through npm wrapper:
+
+```json
+{
+  "mcpServers": {
+    "agentram": {
+      "type": "stdio",
+      "command": "agentram-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If `python` is not the right binary, set `PYTHON`:
+
+```bash
+PYTHON=python3 npx agentram status
+```
+## Install In Coding Agents
+
+### Codex MCP
+
+Add to Codex config:
+
+```toml
+[mcp_servers.agentram]
+command = "agentram-mcp"
+args = []
+```
+
+Fallback if entrypoint is unavailable:
+
+```toml
+[mcp_servers.agentram]
+command = "python"
+args = ["-m", "agentram.mcp_server"]
+```
+
+### Claude Code MCP Command
+
+After installing package:
+
+```bash
+claude mcp add --transport stdio agentram -- python -m agentram.mcp_server
+```
+
+Or:
+
+```bash
+claude mcp add --transport stdio agentram -- agentram-mcp
+```
+
+Check:
+
+```bash
+claude mcp list
+```
+
+Inside Claude Code:
+
+```text
+/mcp
+```
+
+### Claude Code Plugin
+
+This repo includes Claude plugin and marketplace files:
+
+```text
+.claude-plugin/plugin.json
+.claude-plugin/marketplace.json
+.mcp.json
+```
+
+Install from local path inside Claude Code:
+
+```text
+/plugin install C:/path/to/RAMofagent
+```
+
+Or clone first:
+
+```bash
+git clone https://github.com/trancongnghia/AGENT_RAM.git
+cd RAMofagent
+```
+
+Then inside Claude Code:
+
+```text
+/plugin install .
+```
+
+Marketplace install from GitHub:
+
+```text
+/plugin marketplace add agentram https://github.com/trancongnghia/AGENT_RAM
+/plugin install agentram@agentram
+```
+
+If Claude Code uses marketplace name from `.claude-plugin/marketplace.json`, install with:
+
+```text
+/plugin install agentram@agentram-marketplace
+```
+
+The plugin starts AgentRAM using `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentram": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/agentram_mcp_server.py"],
+      "env": {"AGENTRAM_AUTO_INIT": "true"}
+    }
+  }
+}
+```
+
+### Claude Desktop / JSON MCP Clients
+
+```json
+{
+  "mcpServers": {
+    "agentram": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "agentram.mcp_server"]
+    }
+  }
+}
+```
+
+### Other Coding Agents
+
+Any agent can use AgentRAM if it supports stdio MCP servers:
+
+```text
+command: python
+args: ["-m", "agentram.mcp_server"]
+```
+
+Minimum usage pattern:
+
+1. Call `agentram_retrieve` at task start.
+2. Call `agentram_emit_event` after important reads, writes, tool calls, and decisions.
+3. Call `agentram_check_goal_drift` before switching direction.
+4. Call `agentram_retrieve` again near context pressure or resume.
+
+## MCP Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `agentram_init` | Create `.agentram` files without overwriting existing memory. |
+| `agentram_retrieve` | Return Goal Stack plus relevant RAM notes. |
+| `agentram_emit_event` | Append event and optionally ingest into memory. |
+| `agentram_replay_events` | Rebuild memory from `events.jsonl`. |
+| `agentram_read_task_state` | Read RAM notes for one `task_id`. |
+| `agentram_read_goal_state` | Read mission, goals, current task, histories. |
+| `agentram_update_goal_state` | Update Goal Stack fields. |
+| `agentram_check_goal_drift` | Warn only when task appears off-goal. |
+
+### Init
+
+Create `.agentram` files explicitly:
+
+```json
+{}
+```
+
+Returns created file names and paths. Existing files are not overwritten.
+
+### Retrieve
+
+```json
+{
+  "query": "adapter Groq memory writer",
+  "task_id": "codex",
+  "limit": 8
+}
+```
+
+Returns:
+
+- `context`: prompt-ready Goal Stack plus relevant notes.
+- `items`: raw memory items.
+
+### Emit Event
+
+```json
+{
+  "type": "READ_FILE",
+  "payload": {"path": "agentram/adapter.py"},
+  "task_id": "codex",
+  "ingest": true
+}
+```
+
+Supported event types:
+
+```text
+USER_MESSAGE   user request or instruction
+AGENT_MESSAGE  agent output or final answer
+READ_FILE      file opened/read by agent
+WRITE_FILE     file changed by agent
+TOOL_CALL      shell/tool/API action
+DECISION       durable design or implementation choice
+```
+
+### Goal State
+
+```json
+{
+  "mission": "Build shared Working RAM for AI coding agents.",
+  "project_goal": "AgentRAM v1",
+  "current_milestone": "Goal Runtime",
+  "current_goal": "Reduce goal drift",
+  "current_task": "Add goal_state.json",
+  "next_tasks": ["Drift warning"],
+  "goal_history": ["Design schema"],
+  "decision_history": [
+    {
+      "content": "Event log is source of truth.",
+      "source_events": ["evt_123"],
+      "confidence": 0.9
+    }
+  ]
+}
+```
+
+`goal_history` and `decision_history` append instead of replacing previous history.
+
+### Goal Drift Check
+
+Aligned task returns no suggestions:
+
+```json
+{
+  "status": "ok",
+  "aligned": true,
+  "warning": null,
+  "next_actions": []
+}
+```
+
+Off-goal task returns warning:
+
+```json
+{
+  "status": "drift_risk",
+  "aligned": false,
+  "warning": "Potential goal drift. Confirm scope change or update goal_state before continuing.",
+  "next_actions": ["Confirm task belongs to current goal stack."]
+}
+```
+
+## How It Works
+
+```text
+Coding Agent
+  |
+  | emits events through MCP
+  v
+events.jsonl  ---- replayable source of truth
+  |
+  v
+Memory Adapter  heuristic / Ollama / OpenAI-compatible / Anthropic
+  |
+  v
+memory.json     normalized RAM notes
+  |
+  +--> retriever returns relevant notes
+  |
+  v
+goal_state.json mission, goals, current task, history, decisions
+```
+
+Design rules:
+
+- Main agent should not block on long memory work.
+- `events.jsonl` is source of truth.
+- `memory.json` stores normalized notes, not model-specific prose.
+- `goal_state.json` stores durable project direction.
+- Every RAM note links to `source_events`.
+- Current files beat RAM when they conflict.
+
+## Goal Stack
+
+AgentRAM stores durable goal context separately from normal notes:
+
+```text
+Mission
+  -> Project Goal
+    -> Milestones
+      -> Current Goal
+        -> Current Task
+          -> Next Tasks
+```
+
+This helps after compact, restart, model switch, or multi-day work. The agent can recover not only what it was doing, but why the task matters.
+
+## Background Daemon
+
+Use daemon when you want event logging fast and memory ingestion in background.
+
+Run once:
+
+```bash
+agentram-daemon --once
+```
+
+Run continuously:
+
+```bash
+agentram-daemon --interval 1
+```
+
+Replay all events:
+
+```bash
+agentram-daemon --replay-all
+```
+
+Recommended parallel mode:
+
+1. MCP client calls `agentram_emit_event` with `ingest: false`.
+2. `agentram-daemon` tails `events.jsonl`.
+3. Daemon updates `memory.json` independently.
+4. Agent calls `agentram_retrieve` when it needs RAM.
+
+## Wrapper CLI
+
+Use wrapper when an agent does not support MCP yet:
+
+```bash
+agentram-codex "fix auth bug" --dry-run
+```
+
+Run another command with RAM injected through stdin:
+
+```bash
+agentram-codex "fix auth bug" -- codex exec
+```
+
+Useful options:
+
+```text
+--task-id              task namespace, default codex
+--ram-root             storage root, default .agentram in cwd
+--adapter              heuristic | ollama | openai-compatible | anthropic
+--prompt-as-arg        pass prompt as final argv instead of stdin
+--dry-run              print injected prompt only
+```
+
+## Memory Adapters
+
+### Heuristic
+
+Default adapter. No model, no network, deterministic.
+
+```python
+from agentram.orchestrator import AgentRAM
+
+ram = AgentRAM(root=".agentram")
+```
+
+### Ollama
+
+```python
+from agentram.adapter import OllamaMemoryAdapter
+from agentram.orchestrator import AgentRAM
+
+ram = AgentRAM(
+    root=".agentram",
+    adapter=OllamaMemoryAdapter(model="qwen2.5:7b"),
+)
+```
+
+Notes:
+
+- `qwen2.5:7b` is recommended for local JSON reliability.
+- Adapter uses `format: "json"`, `temperature: 0`, and `num_predict: 512`.
+
+### OpenAI-Compatible
+
+Works with Groq, vLLM, LM Studio, llama.cpp server, LocalAI, Ollama `/v1`, OpenRouter-style gateways, and OpenAI-compatible APIs.
+
+```python
+from agentram.adapter import OpenAICompatibleMemoryAdapter
+from agentram.orchestrator import AgentRAM
+
+ram = AgentRAM(
+    root=".agentram",
+    adapter=OpenAICompatibleMemoryAdapter(
+        model="openai/gpt-oss-20b",
+        base_url="https://api.groq.com/openai/v1",
+        api_key="YOUR_KEY",
+        use_response_format=False,
+    ),
+)
+```
+
+### Anthropic Claude API
+
+Uses Anthropic API directly. This is separate from Claude Code's active model and requires `ANTHROPIC_API_KEY`.
+
+```python
+from agentram.adapter import AnthropicMemoryAdapter
+from agentram.orchestrator import AgentRAM
+
+ram = AgentRAM(
+    root=".agentram",
+    adapter=AnthropicMemoryAdapter(
+        model="claude-3-5-haiku-latest",
+        api_key="YOUR_ANTHROPIC_KEY",
+    ),
+)
+```
+
+Wrapper usage:
+
+```bash
+agentram-codex "test Claude memory writer" --adapter anthropic --dry-run
+```
+
+## Environment Config
+
+Copy template:
+
+```bash
+cp .env.example .env
+```
+
+Fill values for OpenAI-compatible/Groq:
+
+```env
+BASE_URL=https://api.groq.com/openai/v1
+Model=openai/gpt-oss-20b
+API_KEY=replace_me
+```
+
+Fill values for Anthropic:
+
+```env
+ANTHROPIC_API_KEY=replace_me
+ANTHROPIC_MODEL=claude-3-5-haiku-latest
+ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
+```
+
+Supported keys:
+
+```text
+base_url: BASE_URL or OPENAI_BASE_URL
+model:    AGENTRAM_MODEL, Model, MODEL, CODEX_MODEL, CODEX_DEFAULT_MODEL, CLAUDE_MODEL, CURSOR_MODEL, or AGENT_MODEL
+api_key:  API_KEY, OPENAI_API_KEY, GROQ_API_KEY, or ANTHROPIC_API_KEY
+timeout:  AGENTRAM_TIMEOUT
+json:     AGENTRAM_RESPONSE_FORMAT=true|false
+anthropic: ANTHROPIC_MODEL, ANTHROPIC_BASE_URL, ANTHROPIC_VERSION
+```
+
+Model selection order:
+
+1. Dedicated memory model: `AGENTRAM_MODEL`, `Model`, or `MODEL`.
+2. Current coding-agent model env: `CODEX_MODEL`, `CODEX_DEFAULT_MODEL`, `CLAUDE_MODEL`, `CURSOR_MODEL`, or `AGENT_MODEL`.
+3. Clear config error if no model found.
+
+Run smoke test:
+
+```bash
+python examples/openai_compatible_smoke.py
+```
+
+## Multiple Projects
+
+Recommended: one RAM root per project.
+
+```text
+project-a/.agentram/
+project-b/.agentram/
+```
+
+If sharing memory intentionally, use explicit roots:
+
+```bash
+agentram-mcp --ram-root C:/AgentRAM/project-a
+agentram-mcp --ram-root C:/AgentRAM/project-b
+```
+
+Use `task_id` to split tasks inside the same project RAM:
+
+```bash
+agentram-codex "fix auth bug" --task-id auth-bug
+agentram-codex "refactor adapter" --task-id adapter-refactor
+```
+
+## Python API
+
+```python
+import asyncio
+
+from agentram.orchestrator import AgentRAM
+from agentram.retriever import MemoryRetriever
+from agentram.schema import Event, EventType
+
+async def main():
+    ram = AgentRAM(root=".agentram")
+    await ram.start()
+    ram.emit(Event(type=EventType.READ_FILE, payload={"path": "main.py"}, task_id="demo"))
+    ram.emit(Event(type=EventType.DECISION, payload={"content": "Use event log as source of truth."}, task_id="demo"))
+    await ram.stop()
+
+    block = MemoryRetriever(ram.memory_store).context_block("event log", task_id="demo")
+    print(block)
+
+asyncio.run(main())
+```
+
+## Model Adapter Contract
+
+Adapters must return normalized memory patches:
+
+```json
+{
+  "patches": [
+    {
+      "op": "upsert",
+      "type": "decision",
+      "content": "Use Event Log as source of truth.",
+      "source_events": ["evt_123"],
+      "related_files": ["agentram/storage.py"],
+      "confidence": 0.9,
+      "scope": "task"
+    }
+  ]
+}
+```
+
+Rules:
+
+- Output JSON only.
+- Use only input event ids.
+- Do not invent files or facts.
+- Keep notes short and factual.
+- Return empty `patches` if nothing important.
+
+## Development
+
+Run tests:
+
+```bash
+python -m pytest -q
+```
+
+Compile check:
+
+```bash
+python -B -m compileall agentram tests codex_ram.py agentram_mcp_server.py agentram_daemon.py examples
+```
+
+Run local demo:
+
+```bash
+python -m agentram.demo
+```
+
+Validate plugin JSON:
+
+```bash
+python -c "import json; [json.load(open(f, encoding='utf-8')) for f in ['.claude-plugin/plugin.json', '.mcp.json']]; print('json ok')"
+```
+
+## Public Repo Hygiene
+
+Do not commit:
+
+- `.env`
+- `.agentram/`
+- `.agentram_*/`
+- `__pycache__/`
+- `.pytest_cache/`
+- real API keys or provider tokens
+
+Use `.env.example` as the shareable template.
+
+## Limitations
+
+- Immediate MCP ingest uses local heuristic adapter.
+- Model-based ingestion is best run through daemon/wrapper configuration.
+- Wrapper CLI records command-level events, not deep internal agent tool events.
+- Rich file/tool hooks need direct agent hooks or disciplined MCP calls.