elephagent 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: elephagent
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Shared memory layer for all your AI coding agents — elephants never forget
|
|
5
|
+
License: MIT License
|
|
6
|
+
|
|
7
|
+
Copyright (c) 2026 Zeeco
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
10
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
11
|
+
in the Software without restriction, including without limitation the rights
|
|
12
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
13
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
14
|
+
furnished to do so, subject to the following conditions:
|
|
15
|
+
|
|
16
|
+
The above copyright notice and this permission notice shall be included in all
|
|
17
|
+
copies or substantial portions of the Software.
|
|
18
|
+
|
|
19
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
20
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
21
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
22
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
23
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
24
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
25
|
+
SOFTWARE.
|
|
26
|
+
|
|
27
|
+
Project-URL: Homepage, https://github.com/zhicongsun/elephagent
|
|
28
|
+
Project-URL: Repository, https://github.com/zhicongsun/elephagent
|
|
29
|
+
Project-URL: Issues, https://github.com/zhicongsun/elephagent/issues
|
|
30
|
+
Keywords: ai,agents,memory,claude,cursor,codex,mcp
|
|
31
|
+
Classifier: Development Status :: 3 - Alpha
|
|
32
|
+
Classifier: Environment :: Console
|
|
33
|
+
Classifier: Intended Audience :: Developers
|
|
34
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
35
|
+
Classifier: Programming Language :: Python :: 3
|
|
36
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
37
|
+
Requires-Python: >=3.9
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
License-File: LICENSE
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
<p align="center">
|
|
43
|
+
<img src="assets/logo.png" width="200" alt="elephagent logo" />
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
<h1 align="center">elephagent</h1>
|
|
47
|
+
|
|
48
|
+
<p align="center">One memory layer for all your AI coding agents.</p>
|
|
49
|
+
|
|
50
|
+
<p align="center">
|
|
51
|
+
<a href="https://pypi.org/project/elephagent/"><img src="https://img.shields.io/pypi/v/elephagent.svg" alt="PyPI" /></a>
|
|
52
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
|
|
53
|
+
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+" /></a>
|
|
54
|
+
<img src="https://img.shields.io/badge/dependencies-none-brightgreen.svg" alt="No dependencies" />
|
|
55
|
+
</p>
|
|
56
|
+
|
|
57
|
+
English | [中文](README.zh.md)
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## The Problem
|
|
62
|
+
|
|
63
|
+
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.
|
|
64
|
+
|
|
65
|
+
## How It Works
|
|
66
|
+
|
|
67
|
+
`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.
|
|
68
|
+
|
|
69
|
+
```mermaid
|
|
70
|
+
flowchart LR
|
|
71
|
+
subgraph repo["Your Repository"]
|
|
72
|
+
direction TB
|
|
73
|
+
src[".agent/\n─────────────\nmemory/\n decisions.md\n workflows.md\n pitfalls.md\ntools/\n registry.json"]
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
src -->|"elephagent build"| CLAUDE["CLAUDE.md\n(Claude Code)"]
|
|
77
|
+
src -->|"elephagent build"| AGENTS["AGENTS.md\n(Codex)"]
|
|
78
|
+
src -->|"elephagent build"| CURSOR[".cursor/rules/\n(Cursor)"]
|
|
79
|
+
src -->|"elephagent build"| MCP[".mcp.json\n(all clients)"]
|
|
80
|
+
|
|
81
|
+
CLAUDE --> cc["Claude Code"]
|
|
82
|
+
AGENTS --> codex["Codex"]
|
|
83
|
+
CURSOR --> cursor["Cursor"]
|
|
84
|
+
MCP --> cc
|
|
85
|
+
MCP --> codex
|
|
86
|
+
MCP --> cursor
|
|
87
|
+
|
|
88
|
+
cc -->|"/remember"| src
|
|
89
|
+
cursor -->|"/remember"| src
|
|
90
|
+
codex -->|"/remember"| src
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Installation
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pip install elephagent
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Or with pipx (recommended for global CLI tools):
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
pipx install elephagent
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Quick Start
|
|
110
|
+
|
|
111
|
+
### Option A — Just talk to your AI agent (recommended)
|
|
112
|
+
|
|
113
|
+
If you use **Claude Code** or **Cursor**, you don't need to type any commands. Just say:
|
|
114
|
+
|
|
115
|
+
| What you say | What happens |
|
|
116
|
+
|---|---|
|
|
117
|
+
| `init memory` | Sets up `.agent/` and generates all platform files |
|
|
118
|
+
| `/remember <note>` | Saves a note to shared memory (use the slash command) |
|
|
119
|
+
| `sync memory` | Commits and pushes memory to Git |
|
|
120
|
+
| `check memory` | Runs a health check on the setup |
|
|
121
|
+
| `add skill <name>` | Creates a new shared skill |
|
|
122
|
+
|
|
123
|
+
> **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.
|
|
124
|
+
|
|
125
|
+
### Option B — CLI
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Initialize in your project
|
|
129
|
+
elephagent init
|
|
130
|
+
|
|
131
|
+
# Add a memory note
|
|
132
|
+
elephagent remember "This repo uses pnpm. Redis is required for API tests."
|
|
133
|
+
|
|
134
|
+
# Rebuild all adapter files
|
|
135
|
+
elephagent build
|
|
136
|
+
|
|
137
|
+
# Verify the setup
|
|
138
|
+
elephagent doctor
|
|
139
|
+
|
|
140
|
+
# Commit and push memory to Git
|
|
141
|
+
elephagent sync -m "update memory"
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Built-in Skills
|
|
147
|
+
|
|
148
|
+
elephagent ships five skills that work across Claude Code, Cursor, and Codex — no commands needed.
|
|
149
|
+
|
|
150
|
+
| Skill | Trigger phrases | What it does |
|
|
151
|
+
|---|---|---|
|
|
152
|
+
| `/init-memory` | "init memory", "set up agent memory" | Bootstrap `.agent/` and generate platform files |
|
|
153
|
+
| `/remember` | `/remember <note>` (slash command) | Save a note from the conversation to shared memory |
|
|
154
|
+
| `/check-memory` | "check memory", "memory status", "doctor" | Health-check the memory setup |
|
|
155
|
+
| `/sync-memory` | "sync memory", "push memory" | Build → commit → push to Git |
|
|
156
|
+
| `/add-skill` | "add skill \<name\>" | Create a new shared skill |
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## All CLI Commands
|
|
161
|
+
|
|
162
|
+
| Command | Description |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `elephagent.py init` | Bootstrap `.agent/` and generate all platform files |
|
|
165
|
+
| `elephagent.py remember "..."` | Append a note and rebuild |
|
|
166
|
+
| `elephagent.py build` | Regenerate all adapter files from `.agent/` |
|
|
167
|
+
| `elephagent.py doctor` | Check that everything is in sync |
|
|
168
|
+
| `elephagent.py sync -m "msg"` | Build → pull → commit → push |
|
|
169
|
+
| `elephagent.py tool list` | List registered MCP servers |
|
|
170
|
+
| `elephagent.py tool add <name>` | Register a new MCP server |
|
|
171
|
+
|
|
172
|
+
### Adding MCP tools
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
# stdio server
|
|
176
|
+
python3 elephagent.py tool add context7 --command npx --arg -y --arg @upstash/context7-mcp
|
|
177
|
+
|
|
178
|
+
# HTTP server with token from env
|
|
179
|
+
python3 elephagent.py tool add figma \
|
|
180
|
+
--url https://mcp.figma.com/mcp \
|
|
181
|
+
--bearer-token-env-var FIGMA_OAUTH_TOKEN
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Built-in MCP Server
|
|
187
|
+
|
|
188
|
+
`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.
|
|
189
|
+
|
|
190
|
+
| Tool | Description |
|
|
191
|
+
|---|---|
|
|
192
|
+
| `agent_memory_read` | Read one or all memory files |
|
|
193
|
+
| `agent_memory_search` | Search across all memory |
|
|
194
|
+
| `agent_memory_append` | Append a durable note |
|
|
195
|
+
| `agent_tool_registry` | Read the shared MCP registry |
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Why Git?
|
|
200
|
+
|
|
201
|
+
- Memory travels with the repo, not the machine.
|
|
202
|
+
- Works in CI, on new laptops, with new teammates.
|
|
203
|
+
- Full history and diffs for every memory change.
|
|
204
|
+
- No third-party service required.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Security
|
|
209
|
+
|
|
210
|
+
Never commit secrets into `.agent/`. Use environment variable references instead:
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
python3 elephagent.py tool add internal-api \
|
|
214
|
+
--url https://example.com/mcp \
|
|
215
|
+
--bearer-token-env-var INTERNAL_API_TOKEN
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`.agent/.gitignore` excludes local scratch files and secret-looking filenames by default.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## Roadmap
|
|
223
|
+
|
|
224
|
+
- [x] Git-synced shared memory
|
|
225
|
+
- [x] Auto-generated adapters for Claude Code, Cursor, Codex
|
|
226
|
+
- [x] Built-in MCP server
|
|
227
|
+
- [x] Shared MCP tool registry
|
|
228
|
+
- [x] Built-in skills for Claude Code, Cursor, Codex
|
|
229
|
+
- [ ] Python SDK (`import elephagent`)
|
|
230
|
+
- [ ] Importers for existing Claude / Cursor / Codex memories
|
|
231
|
+
- [ ] Memory compaction for large histories
|
|
232
|
+
- [ ] `pipx` / Homebrew packaging
|
|
233
|
+
- [ ] GitHub Action for CI validation
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Contributing
|
|
238
|
+
|
|
239
|
+
Issues and PRs are welcome. Before submitting, run:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
python3 elephagent.py build
|
|
243
|
+
python3 elephagent.py doctor
|
|
244
|
+
python3 - <<'PY'
|
|
245
|
+
from pathlib import Path
|
|
246
|
+
for path in ["elephagent.py", ".agent/tools/mcp_server.py"]:
|
|
247
|
+
compile(Path(path).read_text(), path, "exec")
|
|
248
|
+
print(path, "ok")
|
|
249
|
+
PY
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
elephagent.py,sha256=lSW1-wcnFvOyoHgHXWPfmX_MTd_2LFXx8jSlqSBdZz4,41365
|
|
2
|
+
elephagent-0.1.0.dist-info/licenses/LICENSE,sha256=_Teohz1_TLT7lZN1k83Nc72Su8aYHItM5F3Z-dSMRlE,1062
|
|
3
|
+
elephagent-0.1.0.dist-info/METADATA,sha256=wweh2czdcYoOfc7owWgSoLi5eGMRveWfH7YavXSYIao,8322
|
|
4
|
+
elephagent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
5
|
+
elephagent-0.1.0.dist-info/entry_points.txt,sha256=dIiKGMCIDV8ksfG2_YYWPEG95UlQgkAUVMjcxt3ULxg,47
|
|
6
|
+
elephagent-0.1.0.dist-info/top_level.txt,sha256=lGDjLhgo93ZAvZub7jj7eU33qmDw6QFRQpMMn3S-ntc,11
|
|
7
|
+
elephagent-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zeeco
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
elephagent
|