elephagent 0.1.0__tar.gz

elephagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeeco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elephagent-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: elephagent
+Version: 0.1.0
+Summary: Shared memory layer for all your AI coding agents — elephants never forget
+License: MIT License
+        
+        Copyright (c) 2026 Zeeco
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/zhicongsun/elephagent
+Project-URL: Repository, https://github.com/zhicongsun/elephagent
+Project-URL: Issues, https://github.com/zhicongsun/elephagent/issues
+Keywords: ai,agents,memory,claude,cursor,codex,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" width="200" alt="elephagent logo" />
+</p>
+
+<h1 align="center">elephagent</h1>
+
+<p align="center">One memory layer for all your AI coding agents.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/elephagent/"><img src="https://img.shields.io/pypi/v/elephagent.svg" alt="PyPI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+" /></a>
+  <img src="https://img.shields.io/badge/dependencies-none-brightgreen.svg" alt="No dependencies" />
+</p>
+
+English | [中文](README.zh.md)
+
+---
+
+## The Problem
+
+You use Claude Code, Cursor, and Codex. Each stores project knowledge in a different place. Switch machines, add a teammate, or try a new agent — and you start from scratch.
+
+## How It Works
+
+`elephagent` stores everything in one Git-synced `.agent/` directory and renders the config files each tool already knows how to read. Your AI agents can also read and write memory directly via a built-in MCP server.
+
+```mermaid
+flowchart LR
+    subgraph repo["Your Repository"]
+        direction TB
+        src[".agent/\n─────────────\nmemory/\n  decisions.md\n  workflows.md\n  pitfalls.md\ntools/\n  registry.json"]
+    end
+
+    src -->|"elephagent build"| CLAUDE["CLAUDE.md\n(Claude Code)"]
+    src -->|"elephagent build"| AGENTS["AGENTS.md\n(Codex)"]
+    src -->|"elephagent build"| CURSOR[".cursor/rules/\n(Cursor)"]
+    src -->|"elephagent build"| MCP[".mcp.json\n(all clients)"]
+
+    CLAUDE --> cc["Claude Code"]
+    AGENTS --> codex["Codex"]
+    CURSOR --> cursor["Cursor"]
+    MCP --> cc
+    MCP --> codex
+    MCP --> cursor
+
+    cc -->|"/remember"| src
+    cursor -->|"/remember"| src
+    codex -->|"/remember"| src
+```
+
+---
+
+## Installation
+
+```bash
+pip install elephagent
+```
+
+Or with pipx (recommended for global CLI tools):
+
+```bash
+pipx install elephagent
+```
+
+---
+
+## Quick Start
+
+### Option A — Just talk to your AI agent (recommended)
+
+If you use **Claude Code** or **Cursor**, you don't need to type any commands. Just say:
+
+| What you say | What happens |
+|---|---|
+| `init memory` | Sets up `.agent/` and generates all platform files |
+| `/remember <note>` | Saves a note to shared memory (use the slash command) |
+| `sync memory` | Commits and pushes memory to Git |
+| `check memory` | Runs a health check on the setup |
+| `add skill <name>` | Creates a new shared skill |
+
+> **Note:** Use `/remember` as a slash command rather than natural language — phrases like "remember this" may be intercepted by the AI agent's built-in memory system.
+
+### Option B — CLI
+
+```bash
+# Initialize in your project
+elephagent init
+
+# Add a memory note
+elephagent remember "This repo uses pnpm. Redis is required for API tests."
+
+# Rebuild all adapter files
+elephagent build
+
+# Verify the setup
+elephagent doctor
+
+# Commit and push memory to Git
+elephagent sync -m "update memory"
+```
+
+---
+
+## Built-in Skills
+
+elephagent ships five skills that work across Claude Code, Cursor, and Codex — no commands needed.
+
+| Skill | Trigger phrases | What it does |
+|---|---|---|
+| `/init-memory` | "init memory", "set up agent memory" | Bootstrap `.agent/` and generate platform files |
+| `/remember` | `/remember <note>` (slash command) | Save a note from the conversation to shared memory |
+| `/check-memory` | "check memory", "memory status", "doctor" | Health-check the memory setup |
+| `/sync-memory` | "sync memory", "push memory" | Build → commit → push to Git |
+| `/add-skill` | "add skill \<name\>" | Create a new shared skill |
+
+---
+
+## All CLI Commands
+
+| Command | Description |
+|---|---|
+| `elephagent.py init` | Bootstrap `.agent/` and generate all platform files |
+| `elephagent.py remember "..."` | Append a note and rebuild |
+| `elephagent.py build` | Regenerate all adapter files from `.agent/` |
+| `elephagent.py doctor` | Check that everything is in sync |
+| `elephagent.py sync -m "msg"` | Build → pull → commit → push |
+| `elephagent.py tool list` | List registered MCP servers |
+| `elephagent.py tool add <name>` | Register a new MCP server |
+
+### Adding MCP tools
+
+```bash
+# stdio server
+python3 elephagent.py tool add context7 --command npx --arg -y --arg @upstash/context7-mcp
+
+# HTTP server with token from env
+python3 elephagent.py tool add figma \
+  --url https://mcp.figma.com/mcp \
+  --bearer-token-env-var FIGMA_OAUTH_TOKEN
+```
+
+---
+
+## Built-in MCP Server
+
+`elephagent` ships a small MCP server at `.agent/tools/mcp_server.py` that lets agents read and write shared memory directly through the MCP protocol.
+
+| Tool | Description |
+|---|---|
+| `agent_memory_read` | Read one or all memory files |
+| `agent_memory_search` | Search across all memory |
+| `agent_memory_append` | Append a durable note |
+| `agent_tool_registry` | Read the shared MCP registry |
+
+---
+
+## Why Git?
+
+- Memory travels with the repo, not the machine.
+- Works in CI, on new laptops, with new teammates.
+- Full history and diffs for every memory change.
+- No third-party service required.
+
+---
+
+## Security
+
+Never commit secrets into `.agent/`. Use environment variable references instead:
+
+```bash
+python3 elephagent.py tool add internal-api \
+  --url https://example.com/mcp \
+  --bearer-token-env-var INTERNAL_API_TOKEN
+```
+
+`.agent/.gitignore` excludes local scratch files and secret-looking filenames by default.
+
+---
+
+## Roadmap
+
+- [x] Git-synced shared memory
+- [x] Auto-generated adapters for Claude Code, Cursor, Codex
+- [x] Built-in MCP server
+- [x] Shared MCP tool registry
+- [x] Built-in skills for Claude Code, Cursor, Codex
+- [ ] Python SDK (`import elephagent`)
+- [ ] Importers for existing Claude / Cursor / Codex memories
+- [ ] Memory compaction for large histories
+- [ ] `pipx` / Homebrew packaging
+- [ ] GitHub Action for CI validation
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. Before submitting, run:
+
+```bash
+python3 elephagent.py build
+python3 elephagent.py doctor
+python3 - <<'PY'
+from pathlib import Path
+for path in ["elephagent.py", ".agent/tools/mcp_server.py"]:
+    compile(Path(path).read_text(), path, "exec")
+    print(path, "ok")
+PY
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

elephagent-0.1.0/README.md

@@ -0,0 +1,215 @@
+<p align="center">
+  <img src="assets/logo.png" width="200" alt="elephagent logo" />
+</p>
+
+<h1 align="center">elephagent</h1>
+
+<p align="center">One memory layer for all your AI coding agents.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/elephagent/"><img src="https://img.shields.io/pypi/v/elephagent.svg" alt="PyPI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+" /></a>
+  <img src="https://img.shields.io/badge/dependencies-none-brightgreen.svg" alt="No dependencies" />
+</p>
+
+English | [中文](README.zh.md)
+
+---
+
+## The Problem
+
+You use Claude Code, Cursor, and Codex. Each stores project knowledge in a different place. Switch machines, add a teammate, or try a new agent — and you start from scratch.
+
+## How It Works
+
+`elephagent` stores everything in one Git-synced `.agent/` directory and renders the config files each tool already knows how to read. Your AI agents can also read and write memory directly via a built-in MCP server.
+
+```mermaid
+flowchart LR
+    subgraph repo["Your Repository"]
+        direction TB
+        src[".agent/\n─────────────\nmemory/\n  decisions.md\n  workflows.md\n  pitfalls.md\ntools/\n  registry.json"]
+    end
+
+    src -->|"elephagent build"| CLAUDE["CLAUDE.md\n(Claude Code)"]
+    src -->|"elephagent build"| AGENTS["AGENTS.md\n(Codex)"]
+    src -->|"elephagent build"| CURSOR[".cursor/rules/\n(Cursor)"]
+    src -->|"elephagent build"| MCP[".mcp.json\n(all clients)"]
+
+    CLAUDE --> cc["Claude Code"]
+    AGENTS --> codex["Codex"]
+    CURSOR --> cursor["Cursor"]
+    MCP --> cc
+    MCP --> codex
+    MCP --> cursor
+
+    cc -->|"/remember"| src
+    cursor -->|"/remember"| src
+    codex -->|"/remember"| src
+```
+
+---
+
+## Installation
+
+```bash
+pip install elephagent
+```
+
+Or with pipx (recommended for global CLI tools):
+
+```bash
+pipx install elephagent
+```
+
+---
+
+## Quick Start
+
+### Option A — Just talk to your AI agent (recommended)
+
+If you use **Claude Code** or **Cursor**, you don't need to type any commands. Just say:
+
+| What you say | What happens |
+|---|---|
+| `init memory` | Sets up `.agent/` and generates all platform files |
+| `/remember <note>` | Saves a note to shared memory (use the slash command) |
+| `sync memory` | Commits and pushes memory to Git |
+| `check memory` | Runs a health check on the setup |
+| `add skill <name>` | Creates a new shared skill |
+
+> **Note:** Use `/remember` as a slash command rather than natural language — phrases like "remember this" may be intercepted by the AI agent's built-in memory system.
+
+### Option B — CLI
+
+```bash
+# Initialize in your project
+elephagent init
+
+# Add a memory note
+elephagent remember "This repo uses pnpm. Redis is required for API tests."
+
+# Rebuild all adapter files
+elephagent build
+
+# Verify the setup
+elephagent doctor
+
+# Commit and push memory to Git
+elephagent sync -m "update memory"
+```
+
+---
+
+## Built-in Skills
+
+elephagent ships five skills that work across Claude Code, Cursor, and Codex — no commands needed.
+
+| Skill | Trigger phrases | What it does |
+|---|---|---|
+| `/init-memory` | "init memory", "set up agent memory" | Bootstrap `.agent/` and generate platform files |
+| `/remember` | `/remember <note>` (slash command) | Save a note from the conversation to shared memory |
+| `/check-memory` | "check memory", "memory status", "doctor" | Health-check the memory setup |
+| `/sync-memory` | "sync memory", "push memory" | Build → commit → push to Git |
+| `/add-skill` | "add skill \<name\>" | Create a new shared skill |
+
+---
+
+## All CLI Commands
+
+| Command | Description |
+|---|---|
+| `elephagent.py init` | Bootstrap `.agent/` and generate all platform files |
+| `elephagent.py remember "..."` | Append a note and rebuild |
+| `elephagent.py build` | Regenerate all adapter files from `.agent/` |
+| `elephagent.py doctor` | Check that everything is in sync |
+| `elephagent.py sync -m "msg"` | Build → pull → commit → push |
+| `elephagent.py tool list` | List registered MCP servers |
+| `elephagent.py tool add <name>` | Register a new MCP server |
+
+### Adding MCP tools
+
+```bash
+# stdio server
+python3 elephagent.py tool add context7 --command npx --arg -y --arg @upstash/context7-mcp
+
+# HTTP server with token from env
+python3 elephagent.py tool add figma \
+  --url https://mcp.figma.com/mcp \
+  --bearer-token-env-var FIGMA_OAUTH_TOKEN
+```
+
+---
+
+## Built-in MCP Server
+
+`elephagent` ships a small MCP server at `.agent/tools/mcp_server.py` that lets agents read and write shared memory directly through the MCP protocol.
+
+| Tool | Description |
+|---|---|
+| `agent_memory_read` | Read one or all memory files |
+| `agent_memory_search` | Search across all memory |
+| `agent_memory_append` | Append a durable note |
+| `agent_tool_registry` | Read the shared MCP registry |
+
+---
+
+## Why Git?
+
+- Memory travels with the repo, not the machine.
+- Works in CI, on new laptops, with new teammates.
+- Full history and diffs for every memory change.
+- No third-party service required.
+
+---
+
+## Security
+
+Never commit secrets into `.agent/`. Use environment variable references instead:
+
+```bash
+python3 elephagent.py tool add internal-api \
+  --url https://example.com/mcp \
+  --bearer-token-env-var INTERNAL_API_TOKEN
+```
+
+`.agent/.gitignore` excludes local scratch files and secret-looking filenames by default.
+
+---
+
+## Roadmap
+
+- [x] Git-synced shared memory
+- [x] Auto-generated adapters for Claude Code, Cursor, Codex
+- [x] Built-in MCP server
+- [x] Shared MCP tool registry
+- [x] Built-in skills for Claude Code, Cursor, Codex
+- [ ] Python SDK (`import elephagent`)
+- [ ] Importers for existing Claude / Cursor / Codex memories
+- [ ] Memory compaction for large histories
+- [ ] `pipx` / Homebrew packaging
+- [ ] GitHub Action for CI validation
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. Before submitting, run:
+
+```bash
+python3 elephagent.py build
+python3 elephagent.py doctor
+python3 - <<'PY'
+from pathlib import Path
+for path in ["elephagent.py", ".agent/tools/mcp_server.py"]:
+    compile(Path(path).read_text(), path, "exec")
+    print(path, "ok")
+PY
+```
+
+---
+
+## License
+
+[MIT](LICENSE)