stellar-memory 1.0.0__tar.gz

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.
Files changed (120) hide show
  1. stellar_memory-1.0.0/LICENSE +21 -0
  2. stellar_memory-1.0.0/PKG-INFO +241 -0
  3. stellar_memory-1.0.0/README.md +165 -0
  4. stellar_memory-1.0.0/pyproject.toml +79 -0
  5. stellar_memory-1.0.0/setup.cfg +4 -0
  6. stellar_memory-1.0.0/stellar_memory/__init__.py +164 -0
  7. stellar_memory-1.0.0/stellar_memory/adapters/__init__.py +6 -0
  8. stellar_memory-1.0.0/stellar_memory/adapters/langchain.py +67 -0
  9. stellar_memory-1.0.0/stellar_memory/adapters/openai_plugin.py +125 -0
  10. stellar_memory-1.0.0/stellar_memory/adaptive_decay.py +57 -0
  11. stellar_memory-1.0.0/stellar_memory/benchmark.py +229 -0
  12. stellar_memory-1.0.0/stellar_memory/cli.py +460 -0
  13. stellar_memory-1.0.0/stellar_memory/config.py +341 -0
  14. stellar_memory-1.0.0/stellar_memory/connectors/__init__.py +46 -0
  15. stellar_memory-1.0.0/stellar_memory/connectors/api_connector.py +64 -0
  16. stellar_memory-1.0.0/stellar_memory/connectors/file_connector.py +88 -0
  17. stellar_memory-1.0.0/stellar_memory/connectors/web_connector.py +66 -0
  18. stellar_memory-1.0.0/stellar_memory/consolidator.py +72 -0
  19. stellar_memory-1.0.0/stellar_memory/dashboard/__init__.py +18 -0
  20. stellar_memory-1.0.0/stellar_memory/dashboard/app.py +260 -0
  21. stellar_memory-1.0.0/stellar_memory/decay_manager.py +73 -0
  22. stellar_memory-1.0.0/stellar_memory/embedder.py +79 -0
  23. stellar_memory-1.0.0/stellar_memory/emotion.py +111 -0
  24. stellar_memory-1.0.0/stellar_memory/event_bus.py +57 -0
  25. stellar_memory-1.0.0/stellar_memory/event_logger.py +68 -0
  26. stellar_memory-1.0.0/stellar_memory/graph_analyzer.py +225 -0
  27. stellar_memory-1.0.0/stellar_memory/importance_evaluator.py +148 -0
  28. stellar_memory-1.0.0/stellar_memory/llm_adapter.py +95 -0
  29. stellar_memory-1.0.0/stellar_memory/mcp_server.py +376 -0
  30. stellar_memory-1.0.0/stellar_memory/memory_function.py +79 -0
  31. stellar_memory-1.0.0/stellar_memory/memory_graph.py +62 -0
  32. stellar_memory-1.0.0/stellar_memory/metacognition.py +153 -0
  33. stellar_memory-1.0.0/stellar_memory/models.py +395 -0
  34. stellar_memory-1.0.0/stellar_memory/multimodal.py +167 -0
  35. stellar_memory-1.0.0/stellar_memory/namespace.py +47 -0
  36. stellar_memory-1.0.0/stellar_memory/orbit_manager.py +138 -0
  37. stellar_memory-1.0.0/stellar_memory/persistent_graph.py +118 -0
  38. stellar_memory-1.0.0/stellar_memory/providers/__init__.py +140 -0
  39. stellar_memory-1.0.0/stellar_memory/providers/ollama_provider.py +64 -0
  40. stellar_memory-1.0.0/stellar_memory/providers/openai_provider.py +71 -0
  41. stellar_memory-1.0.0/stellar_memory/reasoning.py +293 -0
  42. stellar_memory-1.0.0/stellar_memory/scheduler.py +63 -0
  43. stellar_memory-1.0.0/stellar_memory/security/__init__.py +9 -0
  44. stellar_memory-1.0.0/stellar_memory/security/access_control.py +59 -0
  45. stellar_memory-1.0.0/stellar_memory/security/audit.py +77 -0
  46. stellar_memory-1.0.0/stellar_memory/security/encryption.py +84 -0
  47. stellar_memory-1.0.0/stellar_memory/self_learning.py +341 -0
  48. stellar_memory-1.0.0/stellar_memory/serializer.py +78 -0
  49. stellar_memory-1.0.0/stellar_memory/server.py +605 -0
  50. stellar_memory-1.0.0/stellar_memory/session.py +44 -0
  51. stellar_memory-1.0.0/stellar_memory/stellar.py +946 -0
  52. stellar_memory-1.0.0/stellar_memory/storage/__init__.py +94 -0
  53. stellar_memory-1.0.0/stellar_memory/storage/in_memory.py +61 -0
  54. stellar_memory-1.0.0/stellar_memory/storage/postgres_storage.py +300 -0
  55. stellar_memory-1.0.0/stellar_memory/storage/redis_cache.py +138 -0
  56. stellar_memory-1.0.0/stellar_memory/storage/sqlite_storage.py +192 -0
  57. stellar_memory-1.0.0/stellar_memory/stream.py +113 -0
  58. stellar_memory-1.0.0/stellar_memory/summarizer.py +49 -0
  59. stellar_memory-1.0.0/stellar_memory/sync/__init__.py +7 -0
  60. stellar_memory-1.0.0/stellar_memory/sync/sync_manager.py +104 -0
  61. stellar_memory-1.0.0/stellar_memory/sync/ws_client.py +91 -0
  62. stellar_memory-1.0.0/stellar_memory/sync/ws_server.py +90 -0
  63. stellar_memory-1.0.0/stellar_memory/utils.py +28 -0
  64. stellar_memory-1.0.0/stellar_memory/vector_index.py +233 -0
  65. stellar_memory-1.0.0/stellar_memory/weight_tuner.py +163 -0
  66. stellar_memory-1.0.0/stellar_memory.egg-info/PKG-INFO +241 -0
  67. stellar_memory-1.0.0/stellar_memory.egg-info/SOURCES.txt +118 -0
  68. stellar_memory-1.0.0/stellar_memory.egg-info/dependency_links.txt +1 -0
  69. stellar_memory-1.0.0/stellar_memory.egg-info/entry_points.txt +2 -0
  70. stellar_memory-1.0.0/stellar_memory.egg-info/requires.txt +71 -0
  71. stellar_memory-1.0.0/stellar_memory.egg-info/top_level.txt +1 -0
  72. stellar_memory-1.0.0/tests/test_adapters.py +113 -0
  73. stellar_memory-1.0.0/tests/test_adaptive_decay.py +187 -0
  74. stellar_memory-1.0.0/tests/test_blackhole.py +86 -0
  75. stellar_memory-1.0.0/tests/test_cli.py +82 -0
  76. stellar_memory-1.0.0/tests/test_connectors.py +204 -0
  77. stellar_memory-1.0.0/tests/test_consolidation.py +186 -0
  78. stellar_memory-1.0.0/tests/test_dashboard.py +154 -0
  79. stellar_memory-1.0.0/tests/test_decay.py +158 -0
  80. stellar_memory-1.0.0/tests/test_embedder.py +38 -0
  81. stellar_memory-1.0.0/tests/test_emotion.py +243 -0
  82. stellar_memory-1.0.0/tests/test_event_bus.py +97 -0
  83. stellar_memory-1.0.0/tests/test_event_logger.py +102 -0
  84. stellar_memory-1.0.0/tests/test_graph_analyzer.py +211 -0
  85. stellar_memory-1.0.0/tests/test_health.py +102 -0
  86. stellar_memory-1.0.0/tests/test_importance.py +84 -0
  87. stellar_memory-1.0.0/tests/test_mcp_server.py +75 -0
  88. stellar_memory-1.0.0/tests/test_memory_function.py +108 -0
  89. stellar_memory-1.0.0/tests/test_memory_graph.py +102 -0
  90. stellar_memory-1.0.0/tests/test_middleware.py +75 -0
  91. stellar_memory-1.0.0/tests/test_namespace.py +71 -0
  92. stellar_memory-1.0.0/tests/test_orbit_manager.py +91 -0
  93. stellar_memory-1.0.0/tests/test_p8_init_mcp.py +124 -0
  94. stellar_memory-1.0.0/tests/test_p8_openapi.py +133 -0
  95. stellar_memory-1.0.0/tests/test_p8_quickstart.py +122 -0
  96. stellar_memory-1.0.0/tests/test_p8_version.py +56 -0
  97. stellar_memory-1.0.0/tests/test_p9_benchmark.py +131 -0
  98. stellar_memory-1.0.0/tests/test_p9_metacognition.py +188 -0
  99. stellar_memory-1.0.0/tests/test_p9_multimodal.py +164 -0
  100. stellar_memory-1.0.0/tests/test_p9_reasoning.py +171 -0
  101. stellar_memory-1.0.0/tests/test_p9_self_learning.py +183 -0
  102. stellar_memory-1.0.0/tests/test_packaging.py +55 -0
  103. stellar_memory-1.0.0/tests/test_performance.py +115 -0
  104. stellar_memory-1.0.0/tests/test_persistent_graph.py +115 -0
  105. stellar_memory-1.0.0/tests/test_providers.py +130 -0
  106. stellar_memory-1.0.0/tests/test_recall_boost.py +136 -0
  107. stellar_memory-1.0.0/tests/test_security.py +284 -0
  108. stellar_memory-1.0.0/tests/test_semantic_search.py +90 -0
  109. stellar_memory-1.0.0/tests/test_serializer.py +154 -0
  110. stellar_memory-1.0.0/tests/test_server.py +137 -0
  111. stellar_memory-1.0.0/tests/test_session.py +117 -0
  112. stellar_memory-1.0.0/tests/test_stellar.py +115 -0
  113. stellar_memory-1.0.0/tests/test_storage.py +211 -0
  114. stellar_memory-1.0.0/tests/test_storage_backend.py +208 -0
  115. stellar_memory-1.0.0/tests/test_stream.py +112 -0
  116. stellar_memory-1.0.0/tests/test_summarizer.py +132 -0
  117. stellar_memory-1.0.0/tests/test_sync.py +204 -0
  118. stellar_memory-1.0.0/tests/test_tuner_integration.py +99 -0
  119. stellar_memory-1.0.0/tests/test_vector_index.py +163 -0
  120. stellar_memory-1.0.0/tests/test_weight_tuner.py +131 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 sangjun0000
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,241 @@
1
+ Metadata-Version: 2.1
2
+ Name: stellar-memory
3
+ Version: 1.0.0
4
+ Summary: A celestial-structure-based AI memory management system - Give any AI human-like memory
5
+ Author: Stellar Memory Contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://sangjun0000.github.io/stellar-memory/
8
+ Project-URL: Repository, https://github.com/sangjun0000/stellar-memory
9
+ Project-URL: Documentation, https://github.com/sangjun0000/stellar-memory#readme
10
+ Project-URL: Changelog, https://github.com/sangjun0000/stellar-memory/blob/main/CHANGELOG.md
11
+ Keywords: ai,memory,llm,mcp,recall,context
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Provides-Extra: embedding
24
+ Requires-Dist: sentence-transformers>=2.2.0; extra == "embedding"
25
+ Provides-Extra: llm
26
+ Requires-Dist: anthropic>=0.18.0; extra == "llm"
27
+ Provides-Extra: openai
28
+ Requires-Dist: openai>=1.0.0; extra == "openai"
29
+ Provides-Extra: ollama
30
+ Requires-Dist: requests>=2.28.0; extra == "ollama"
31
+ Provides-Extra: ai
32
+ Requires-Dist: sentence-transformers>=2.2.0; extra == "ai"
33
+ Requires-Dist: anthropic>=0.18.0; extra == "ai"
34
+ Provides-Extra: mcp
35
+ Requires-Dist: mcp[cli]>=1.2.0; extra == "mcp"
36
+ Provides-Extra: cli
37
+ Requires-Dist: mcp[cli]>=1.2.0; extra == "cli"
38
+ Provides-Extra: postgres
39
+ Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
40
+ Provides-Extra: redis
41
+ Requires-Dist: redis>=5.0.0; extra == "redis"
42
+ Provides-Extra: security
43
+ Requires-Dist: cryptography>=42.0.0; extra == "security"
44
+ Provides-Extra: sync
45
+ Requires-Dist: websockets>=12.0; extra == "sync"
46
+ Provides-Extra: connectors
47
+ Requires-Dist: httpx>=0.27.0; extra == "connectors"
48
+ Provides-Extra: server
49
+ Requires-Dist: fastapi>=0.110.0; extra == "server"
50
+ Requires-Dist: uvicorn>=0.29.0; extra == "server"
51
+ Provides-Extra: dashboard
52
+ Requires-Dist: fastapi>=0.110.0; extra == "dashboard"
53
+ Requires-Dist: uvicorn>=0.29.0; extra == "dashboard"
54
+ Provides-Extra: adapters
55
+ Requires-Dist: langchain-core>=0.1.0; extra == "adapters"
56
+ Provides-Extra: full
57
+ Requires-Dist: sentence-transformers>=2.2.0; extra == "full"
58
+ Requires-Dist: anthropic>=0.18.0; extra == "full"
59
+ Requires-Dist: openai>=1.0.0; extra == "full"
60
+ Requires-Dist: requests>=2.28.0; extra == "full"
61
+ Requires-Dist: mcp[cli]>=1.2.0; extra == "full"
62
+ Requires-Dist: asyncpg>=0.29.0; extra == "full"
63
+ Requires-Dist: redis>=5.0.0; extra == "full"
64
+ Requires-Dist: cryptography>=42.0.0; extra == "full"
65
+ Requires-Dist: websockets>=12.0; extra == "full"
66
+ Requires-Dist: httpx>=0.27.0; extra == "full"
67
+ Requires-Dist: fastapi>=0.110.0; extra == "full"
68
+ Requires-Dist: uvicorn>=0.29.0; extra == "full"
69
+ Requires-Dist: langchain-core>=0.1.0; extra == "full"
70
+ Provides-Extra: docs
71
+ Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
72
+ Provides-Extra: dev
73
+ Requires-Dist: pytest>=7.0; extra == "dev"
74
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
75
+ Requires-Dist: httpx>=0.27.0; extra == "dev"
76
+
77
+ # Stellar Memory
78
+
79
+ > Give any AI human-like memory. Built on a celestial structure.
80
+
81
+ [![PyPI](https://img.shields.io/pypi/v/stellar-memory)](https://pypi.org/project/stellar-memory/)
82
+ [![Tests](https://img.shields.io/github/actions/workflow/status/sangjun0000/stellar-memory/ci.yml?label=tests)](https://github.com/sangjun0000/stellar-memory/actions)
83
+ [![Python](https://img.shields.io/pypi/pyversions/stellar-memory)](https://pypi.org/project/stellar-memory/)
84
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
85
+
86
+ ```
87
+ Cloud (Zone 4) - Near-forgotten
88
+ ╱ ╲
89
+ Belt (Zone 3) - Less important
90
+ ╱ ╲
91
+ Outer (Zone 2) - Regular memories
92
+ ╱ ╲
93
+ Inner (Zone 1) - Important memories
94
+ ╱ ╲
95
+ ★ Core (Zone 0) ★
96
+ Most important memories
97
+ Always accessible
98
+ ```
99
+
100
+ ## Why Stellar Memory?
101
+
102
+ | | Traditional AI | With Stellar Memory |
103
+ |---|---|---|
104
+ | Memory | Forgets after context window | Remembers across sessions |
105
+ | Importance | Treats all info equally | Ranks by importance score |
106
+ | Organization | Flat key-value store | 5-zone celestial hierarchy |
107
+ | Forgetting | Manual deletion only | Adaptive decay, like humans |
108
+
109
+ ## Quick Start
110
+
111
+ ```python
112
+ from stellar_memory import StellarMemory
113
+
114
+ memory = StellarMemory()
115
+
116
+ # Store memories with different importance
117
+ memory.store("User prefers dark mode", importance=0.8)
118
+ memory.store("The weather is nice today", importance=0.2)
119
+ memory.store("Project deadline is March 1st", importance=0.9)
120
+
121
+ # Recall relevant memories
122
+ results = memory.recall("user preference")
123
+ print(results[0].content) # "User prefers dark mode"
124
+
125
+ # Check statistics
126
+ stats = memory.stats()
127
+ print(f"Total: {stats.total_memories} memories across 5 zones")
128
+
129
+ memory.stop()
130
+ ```
131
+
132
+ ## Installation
133
+
134
+ ```bash
135
+ # Core library (zero dependencies)
136
+ pip install stellar-memory
137
+
138
+ # With REST API server
139
+ pip install stellar-memory[server]
140
+
141
+ # With MCP server (Claude Code / Cursor)
142
+ pip install stellar-memory[mcp]
143
+
144
+ # Everything
145
+ pip install stellar-memory[full]
146
+ ```
147
+
148
+ **Requirements**: Python 3.10+
149
+
150
+ ## Key Features
151
+
152
+ - **5-Zone Memory Hierarchy** - Solar system model: Core, Inner, Outer, Belt, Cloud
153
+ - **Black Hole Prevention** - Logarithmic recall function prevents memory overflow
154
+ - **Emotional Memory** - 6-dimensional emotion vectors (joy, sadness, anger, fear, surprise, disgust)
155
+ - **Memory Function** - `I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)`
156
+ - **MCP Server** - Claude Code and Cursor integration via Model Context Protocol
157
+ - **REST API** - FastAPI with Swagger UI and ReDoc
158
+ - **Graph Analytics** - Memory relationships, communities, centrality analysis
159
+ - **Multi-Agent Sync** - CRDT-based conflict resolution + WebSocket
160
+ - **Adaptive Decay** - Human-like forgetting with reinforcement on recall
161
+ - **LangChain / OpenAI Adapters** - Drop-in integrations
162
+
163
+ ## Use Cases
164
+
165
+ - **AI Chatbot** - Persistent memory across conversations
166
+ - **Personal Assistant** - Learn user preferences over time
167
+ - **Code Assistant** - Remember project context and decisions
168
+ - **Knowledge Management** - Organize and retrieve information naturally
169
+
170
+ ## Four Ways to Use
171
+
172
+ ### 1. Python Library
173
+
174
+ ```python
175
+ from stellar_memory import StellarMemory, StellarConfig, EmotionConfig
176
+
177
+ config = StellarConfig(emotion=EmotionConfig(enabled=True))
178
+ memory = StellarMemory(config)
179
+
180
+ item = memory.store("Got promoted today!", importance=0.9)
181
+ print(f"Emotion: {item.emotion.dominant}") # "joy"
182
+ ```
183
+
184
+ ### 2. REST API
185
+
186
+ ```bash
187
+ stellar-memory serve-api
188
+ # Open http://localhost:9000/docs for Swagger UI
189
+ ```
190
+
191
+ ```bash
192
+ curl -X POST http://localhost:9000/api/v1/store \
193
+ -H "Content-Type: application/json" \
194
+ -d '{"content": "Remember this", "importance": 0.7}'
195
+ ```
196
+
197
+ ### 3. MCP Server (Claude Code / Cursor)
198
+
199
+ ```bash
200
+ stellar-memory init-mcp --ide claude
201
+ # Restart Claude Desktop - memory tools are now available
202
+ ```
203
+
204
+ ### 4. Docker
205
+
206
+ ```bash
207
+ docker-compose up stellar
208
+ # API available at http://localhost:9000
209
+ ```
210
+
211
+ ## Architecture
212
+
213
+ The memory function determines where each memory lives:
214
+
215
+ ```
216
+ I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)
217
+
218
+ R(m) = log(1 + recall_count) # Recall (log-bounded)
219
+ F(m) = -α · time_since_recall # Freshness (decays, resets on recall)
220
+ A(m) = ai_evaluated_importance # Arbitrary importance (AI-judged)
221
+ C(m) = connection_strength # Graph connectivity
222
+ E(m) = emotional_intensity # Emotion weight
223
+ ```
224
+
225
+ Memories are periodically **reorbited** - moved between zones based on their total score. High-scoring memories migrate toward the Core; low-scoring ones drift to the Cloud and eventually evaporate.
226
+
227
+ ## Documentation
228
+
229
+ - [Getting Started](https://github.com/sangjun0000/stellar-memory/blob/main/docs/getting-started/)
230
+ - [API Reference](https://github.com/sangjun0000/stellar-memory/blob/main/docs/api-reference/)
231
+ - [REST API](https://github.com/sangjun0000/stellar-memory/blob/main/docs/rest-api/)
232
+ - [MCP Integration](https://github.com/sangjun0000/stellar-memory/blob/main/docs/mcp/claude-code/)
233
+ - [Guides](https://github.com/sangjun0000/stellar-memory/blob/main/docs/guides/chatbot/)
234
+
235
+ ## Contributing
236
+
237
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
238
+
239
+ ## License
240
+
241
+ MIT License - see [LICENSE](LICENSE) for details.
@@ -0,0 +1,165 @@
1
+ # Stellar Memory
2
+
3
+ > Give any AI human-like memory. Built on a celestial structure.
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/stellar-memory)](https://pypi.org/project/stellar-memory/)
6
+ [![Tests](https://img.shields.io/github/actions/workflow/status/sangjun0000/stellar-memory/ci.yml?label=tests)](https://github.com/sangjun0000/stellar-memory/actions)
7
+ [![Python](https://img.shields.io/pypi/pyversions/stellar-memory)](https://pypi.org/project/stellar-memory/)
8
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
+
10
+ ```
11
+ Cloud (Zone 4) - Near-forgotten
12
+ ╱ ╲
13
+ Belt (Zone 3) - Less important
14
+ ╱ ╲
15
+ Outer (Zone 2) - Regular memories
16
+ ╱ ╲
17
+ Inner (Zone 1) - Important memories
18
+ ╱ ╲
19
+ ★ Core (Zone 0) ★
20
+ Most important memories
21
+ Always accessible
22
+ ```
23
+
24
+ ## Why Stellar Memory?
25
+
26
+ | | Traditional AI | With Stellar Memory |
27
+ |---|---|---|
28
+ | Memory | Forgets after context window | Remembers across sessions |
29
+ | Importance | Treats all info equally | Ranks by importance score |
30
+ | Organization | Flat key-value store | 5-zone celestial hierarchy |
31
+ | Forgetting | Manual deletion only | Adaptive decay, like humans |
32
+
33
+ ## Quick Start
34
+
35
+ ```python
36
+ from stellar_memory import StellarMemory
37
+
38
+ memory = StellarMemory()
39
+
40
+ # Store memories with different importance
41
+ memory.store("User prefers dark mode", importance=0.8)
42
+ memory.store("The weather is nice today", importance=0.2)
43
+ memory.store("Project deadline is March 1st", importance=0.9)
44
+
45
+ # Recall relevant memories
46
+ results = memory.recall("user preference")
47
+ print(results[0].content) # "User prefers dark mode"
48
+
49
+ # Check statistics
50
+ stats = memory.stats()
51
+ print(f"Total: {stats.total_memories} memories across 5 zones")
52
+
53
+ memory.stop()
54
+ ```
55
+
56
+ ## Installation
57
+
58
+ ```bash
59
+ # Core library (zero dependencies)
60
+ pip install stellar-memory
61
+
62
+ # With REST API server
63
+ pip install stellar-memory[server]
64
+
65
+ # With MCP server (Claude Code / Cursor)
66
+ pip install stellar-memory[mcp]
67
+
68
+ # Everything
69
+ pip install stellar-memory[full]
70
+ ```
71
+
72
+ **Requirements**: Python 3.10+
73
+
74
+ ## Key Features
75
+
76
+ - **5-Zone Memory Hierarchy** - Solar system model: Core, Inner, Outer, Belt, Cloud
77
+ - **Black Hole Prevention** - Logarithmic recall function prevents memory overflow
78
+ - **Emotional Memory** - 6-dimensional emotion vectors (joy, sadness, anger, fear, surprise, disgust)
79
+ - **Memory Function** - `I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)`
80
+ - **MCP Server** - Claude Code and Cursor integration via Model Context Protocol
81
+ - **REST API** - FastAPI with Swagger UI and ReDoc
82
+ - **Graph Analytics** - Memory relationships, communities, centrality analysis
83
+ - **Multi-Agent Sync** - CRDT-based conflict resolution + WebSocket
84
+ - **Adaptive Decay** - Human-like forgetting with reinforcement on recall
85
+ - **LangChain / OpenAI Adapters** - Drop-in integrations
86
+
87
+ ## Use Cases
88
+
89
+ - **AI Chatbot** - Persistent memory across conversations
90
+ - **Personal Assistant** - Learn user preferences over time
91
+ - **Code Assistant** - Remember project context and decisions
92
+ - **Knowledge Management** - Organize and retrieve information naturally
93
+
94
+ ## Four Ways to Use
95
+
96
+ ### 1. Python Library
97
+
98
+ ```python
99
+ from stellar_memory import StellarMemory, StellarConfig, EmotionConfig
100
+
101
+ config = StellarConfig(emotion=EmotionConfig(enabled=True))
102
+ memory = StellarMemory(config)
103
+
104
+ item = memory.store("Got promoted today!", importance=0.9)
105
+ print(f"Emotion: {item.emotion.dominant}") # "joy"
106
+ ```
107
+
108
+ ### 2. REST API
109
+
110
+ ```bash
111
+ stellar-memory serve-api
112
+ # Open http://localhost:9000/docs for Swagger UI
113
+ ```
114
+
115
+ ```bash
116
+ curl -X POST http://localhost:9000/api/v1/store \
117
+ -H "Content-Type: application/json" \
118
+ -d '{"content": "Remember this", "importance": 0.7}'
119
+ ```
120
+
121
+ ### 3. MCP Server (Claude Code / Cursor)
122
+
123
+ ```bash
124
+ stellar-memory init-mcp --ide claude
125
+ # Restart Claude Desktop - memory tools are now available
126
+ ```
127
+
128
+ ### 4. Docker
129
+
130
+ ```bash
131
+ docker-compose up stellar
132
+ # API available at http://localhost:9000
133
+ ```
134
+
135
+ ## Architecture
136
+
137
+ The memory function determines where each memory lives:
138
+
139
+ ```
140
+ I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)
141
+
142
+ R(m) = log(1 + recall_count) # Recall (log-bounded)
143
+ F(m) = -α · time_since_recall # Freshness (decays, resets on recall)
144
+ A(m) = ai_evaluated_importance # Arbitrary importance (AI-judged)
145
+ C(m) = connection_strength # Graph connectivity
146
+ E(m) = emotional_intensity # Emotion weight
147
+ ```
148
+
149
+ Memories are periodically **reorbited** - moved between zones based on their total score. High-scoring memories migrate toward the Core; low-scoring ones drift to the Cloud and eventually evaporate.
150
+
151
+ ## Documentation
152
+
153
+ - [Getting Started](https://github.com/sangjun0000/stellar-memory/blob/main/docs/getting-started/)
154
+ - [API Reference](https://github.com/sangjun0000/stellar-memory/blob/main/docs/api-reference/)
155
+ - [REST API](https://github.com/sangjun0000/stellar-memory/blob/main/docs/rest-api/)
156
+ - [MCP Integration](https://github.com/sangjun0000/stellar-memory/blob/main/docs/mcp/claude-code/)
157
+ - [Guides](https://github.com/sangjun0000/stellar-memory/blob/main/docs/guides/chatbot/)
158
+
159
+ ## Contributing
160
+
161
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
162
+
163
+ ## License
164
+
165
+ MIT License - see [LICENSE](LICENSE) for details.
@@ -0,0 +1,79 @@
1
+ [project]
2
+ name = "stellar-memory"
3
+ version = "1.0.0"
4
+ description = "A celestial-structure-based AI memory management system - Give any AI human-like memory"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = {text = "MIT"}
8
+ authors = [{name = "Stellar Memory Contributors"}]
9
+ classifiers = [
10
+ "Development Status :: 5 - Production/Stable",
11
+ "Intended Audience :: Developers",
12
+ "Programming Language :: Python :: 3",
13
+ "Programming Language :: Python :: 3.10",
14
+ "Programming Language :: Python :: 3.11",
15
+ "Programming Language :: Python :: 3.12",
16
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
17
+ "Topic :: Software Development :: Libraries :: Python Modules",
18
+ ]
19
+ keywords = ["ai", "memory", "llm", "mcp", "recall", "context"]
20
+ dependencies = []
21
+
22
+ [project.urls]
23
+ Homepage = "https://sangjun0000.github.io/stellar-memory/"
24
+ Repository = "https://github.com/sangjun0000/stellar-memory"
25
+ Documentation = "https://github.com/sangjun0000/stellar-memory#readme"
26
+ Changelog = "https://github.com/sangjun0000/stellar-memory/blob/main/CHANGELOG.md"
27
+
28
+ [project.scripts]
29
+ stellar-memory = "stellar_memory.cli:main"
30
+
31
+ [project.optional-dependencies]
32
+ # Core AI features
33
+ embedding = ["sentence-transformers>=2.2.0"]
34
+ llm = ["anthropic>=0.18.0"]
35
+ openai = ["openai>=1.0.0"]
36
+ ollama = ["requests>=2.28.0"]
37
+ ai = ["sentence-transformers>=2.2.0", "anthropic>=0.18.0"]
38
+
39
+ # Protocols
40
+ mcp = ["mcp[cli]>=1.2.0"]
41
+ cli = ["mcp[cli]>=1.2.0"]
42
+
43
+ # Infrastructure
44
+ postgres = ["asyncpg>=0.29.0"]
45
+ redis = ["redis>=5.0.0"]
46
+ security = ["cryptography>=42.0.0"]
47
+ sync = ["websockets>=12.0"]
48
+ connectors = ["httpx>=0.27.0"]
49
+
50
+ # Server & Dashboard
51
+ server = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
52
+ dashboard = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
53
+
54
+ # Adapters
55
+ adapters = ["langchain-core>=0.1.0"]
56
+
57
+ # Full install
58
+ full = [
59
+ "sentence-transformers>=2.2.0", "anthropic>=0.18.0", "openai>=1.0.0",
60
+ "requests>=2.28.0", "mcp[cli]>=1.2.0",
61
+ "asyncpg>=0.29.0", "redis>=5.0.0", "cryptography>=42.0.0",
62
+ "websockets>=12.0", "httpx>=0.27.0",
63
+ "fastapi>=0.110.0", "uvicorn>=0.29.0",
64
+ "langchain-core>=0.1.0",
65
+ ]
66
+
67
+ docs = ["mkdocs-material>=9.5.0"]
68
+
69
+ dev = ["pytest>=7.0", "pytest-cov>=4.0", "httpx>=0.27.0"]
70
+
71
+ [tool.setuptools.packages.find]
72
+ include = ["stellar_memory*"]
73
+
74
+ [build-system]
75
+ requires = ["setuptools>=68.0,<75", "wheel"]
76
+ build-backend = "setuptools.build_meta"
77
+
78
+ [tool.pytest.ini_options]
79
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,164 @@
1
+ """Stellar Memory - A celestial-structure-based AI memory management system.
2
+
3
+ Give any AI human-like memory, built on a celestial structure.
4
+ """
5
+
6
+ from stellar_memory.stellar import StellarMemory
7
+ from stellar_memory.config import (
8
+ StellarConfig, MemoryFunctionConfig, ZoneConfig,
9
+ EmbedderConfig, LLMConfig, TunerConfig,
10
+ ConsolidationConfig, SessionConfig,
11
+ EventConfig, NamespaceConfig, GraphConfig,
12
+ DecayConfig, EventLoggerConfig, RecallConfig,
13
+ VectorIndexConfig, SummarizationConfig,
14
+ AdaptiveDecayConfig, GraphAnalyticsConfig,
15
+ StorageConfig, SyncConfig, SecurityConfig,
16
+ ConnectorConfig, DashboardConfig,
17
+ EmotionConfig, ServerConfig,
18
+ MetacognitionConfig, SelfLearningConfig,
19
+ MultimodalConfig, ReasoningConfig, BenchmarkConfig,
20
+ )
21
+ from stellar_memory.models import (
22
+ MemoryItem, ScoreBreakdown, ReorbitResult, MemoryStats,
23
+ EvaluationResult, FeedbackRecord,
24
+ ConsolidationResult, SessionInfo, MemorySnapshot,
25
+ MemoryEdge, DecayResult, HealthStatus, SummarizationResult,
26
+ ChangeEvent, AccessRole, IngestResult, ZoneDistribution,
27
+ EmotionVector, TimelineEntry,
28
+ IntrospectionResult, ConfidentRecall, RecallLog,
29
+ OptimizationReport, ReasoningResult, Contradiction,
30
+ BenchmarkReport,
31
+ )
32
+ from stellar_memory.event_bus import EventBus
33
+ from stellar_memory.memory_graph import MemoryGraph
34
+ from stellar_memory.persistent_graph import PersistentMemoryGraph
35
+ from stellar_memory.namespace import NamespaceManager
36
+ from stellar_memory.decay_manager import DecayManager
37
+ from stellar_memory.event_logger import EventLogger
38
+ from stellar_memory.llm_adapter import MemoryMiddleware, AnthropicAdapter
39
+ from stellar_memory.vector_index import VectorIndex, BruteForceIndex, BallTreeIndex
40
+ from stellar_memory.summarizer import MemorySummarizer
41
+ from stellar_memory.adaptive_decay import AdaptiveDecayManager
42
+ from stellar_memory.graph_analyzer import GraphAnalyzer, GraphStats, CentralityResult
43
+ from stellar_memory.providers import ProviderRegistry
44
+ from stellar_memory.storage import StorageBackend
45
+ from stellar_memory.security.encryption import EncryptionManager
46
+ from stellar_memory.security.access_control import AccessControl
47
+ from stellar_memory.security.audit import SecurityAudit
48
+ from stellar_memory.sync import MemorySyncManager
49
+ from stellar_memory.emotion import EmotionAnalyzer
50
+ from stellar_memory.stream import MemoryStream
51
+ from stellar_memory.metacognition import Introspector, ConfidenceScorer
52
+ from stellar_memory.multimodal import (
53
+ ContentTypeHandler, TextHandler, CodeHandler, JsonHandler,
54
+ get_handler, detect_content_type,
55
+ )
56
+ from stellar_memory.self_learning import PatternCollector, WeightOptimizer
57
+ from stellar_memory.reasoning import MemoryReasoner, ContradictionDetector
58
+ from stellar_memory.benchmark import StandardDataset, MemoryBenchmark
59
+
60
+ try:
61
+ from importlib.metadata import version as _pkg_version
62
+ __version__ = _pkg_version("stellar-memory")
63
+ except Exception:
64
+ __version__ = "1.0.0"
65
+
66
+ __all__ = [
67
+ "StellarMemory",
68
+ "StellarConfig",
69
+ "MemoryFunctionConfig",
70
+ "ZoneConfig",
71
+ "EmbedderConfig",
72
+ "LLMConfig",
73
+ "TunerConfig",
74
+ "ConsolidationConfig",
75
+ "SessionConfig",
76
+ "EventConfig",
77
+ "NamespaceConfig",
78
+ "GraphConfig",
79
+ "DecayConfig",
80
+ "EventLoggerConfig",
81
+ "RecallConfig",
82
+ "VectorIndexConfig",
83
+ "SummarizationConfig",
84
+ "AdaptiveDecayConfig",
85
+ "GraphAnalyticsConfig",
86
+ "MemoryItem",
87
+ "ScoreBreakdown",
88
+ "ReorbitResult",
89
+ "MemoryStats",
90
+ "EvaluationResult",
91
+ "FeedbackRecord",
92
+ "ConsolidationResult",
93
+ "SessionInfo",
94
+ "MemorySnapshot",
95
+ "MemoryEdge",
96
+ "DecayResult",
97
+ "HealthStatus",
98
+ "SummarizationResult",
99
+ "EventBus",
100
+ "MemoryGraph",
101
+ "PersistentMemoryGraph",
102
+ "NamespaceManager",
103
+ "DecayManager",
104
+ "EventLogger",
105
+ "MemoryMiddleware",
106
+ "AnthropicAdapter",
107
+ "VectorIndex",
108
+ "BruteForceIndex",
109
+ "BallTreeIndex",
110
+ "MemorySummarizer",
111
+ "AdaptiveDecayManager",
112
+ "GraphAnalyzer",
113
+ "GraphStats",
114
+ "CentralityResult",
115
+ "ProviderRegistry",
116
+ "StorageConfig",
117
+ "SyncConfig",
118
+ "SecurityConfig",
119
+ "ConnectorConfig",
120
+ "DashboardConfig",
121
+ "ChangeEvent",
122
+ "AccessRole",
123
+ "IngestResult",
124
+ "ZoneDistribution",
125
+ "StorageBackend",
126
+ "EncryptionManager",
127
+ "AccessControl",
128
+ "SecurityAudit",
129
+ "MemorySyncManager",
130
+ # P7
131
+ "EmotionConfig",
132
+ "ServerConfig",
133
+ "EmotionVector",
134
+ "TimelineEntry",
135
+ "EmotionAnalyzer",
136
+ "MemoryStream",
137
+ # P9
138
+ "MetacognitionConfig",
139
+ "SelfLearningConfig",
140
+ "MultimodalConfig",
141
+ "ReasoningConfig",
142
+ "BenchmarkConfig",
143
+ "IntrospectionResult",
144
+ "ConfidentRecall",
145
+ "RecallLog",
146
+ "OptimizationReport",
147
+ "ReasoningResult",
148
+ "Contradiction",
149
+ "BenchmarkReport",
150
+ "Introspector",
151
+ "ConfidenceScorer",
152
+ "ContentTypeHandler",
153
+ "TextHandler",
154
+ "CodeHandler",
155
+ "JsonHandler",
156
+ "get_handler",
157
+ "detect_content_type",
158
+ "PatternCollector",
159
+ "WeightOptimizer",
160
+ "MemoryReasoner",
161
+ "ContradictionDetector",
162
+ "StandardDataset",
163
+ "MemoryBenchmark",
164
+ ]
@@ -0,0 +1,6 @@
1
+ """Stellar Memory adapters for AI frameworks."""
2
+
3
+ from stellar_memory.adapters.langchain import StellarLangChainMemory
4
+ from stellar_memory.adapters.openai_plugin import OpenAIMemoryPlugin, STELLAR_TOOLS
5
+
6
+ __all__ = ["StellarLangChainMemory", "OpenAIMemoryPlugin", "STELLAR_TOOLS"]