An AI that grows with you.

An open-source autonomous AI agent with a persistent personality, long-term memory that actually forgets, and a visible reasoning trail — in one Python file with one dependency.

Most AI agents are built to complete tasks. Polaris is built to remember, reflect, learn, and grow. Rather than behaving like a stateless chatbot, it maintains an evolving internal state that influences its planning, reasoning, and communication.

Runs against any OpenAI-compatible endpoint — hosted or local — and keeps its entire state in plain JSON files next to your project.

git clone https://github.com/tkc1248580868-debug/-polaris-agent.git
cd ./-polaris-agent
pip install -r requirements.txt

export OPENAI_API_KEY=sk-...
python polaris_1_1_6_memorycurve.py

Prefer a local model? No API key needed:

export MINIAGENT_BACKEND=ollama        # or: lmstudio
export MINIAGENT_MODEL=qwen2.5:14b
python polaris_1_1_6_memorycurve.py

Verify the install without spending a single token:

python polaris_1_1_6_memorycurve.py --selftest    # exits non-zero if anything fails

or /selftest from inside a session.

Twenty-four checks covering the sandbox, the shell guard, file-edit safety, context assembly, the trace tree, and the memory curve. No API key required.

Requirements: Python 3.10+, and an OpenAI-compatible endpoint. Works on Windows, Linux, and macOS. The only dependency is openai — every other import is from the standard library.

Tested against OpenAI, Gemini, Claude, Ollama, and LM Studio.

Most agents' "long-term memory" is an append-only log that grows until it is useless. Polaris puts every memory on an Ebbinghaus forgetting curve:

R = exp(-t / S)

Each memory decays on its own schedule, and every time it is recalled it decays more slowly — with a real spacing effect, so cramming does not work here either. Memories that stop mattering fade out of the prompt on their own; memories that keep coming up become permanent. Nothing is ever deleted behind your back — faded entries go dormant and a specific enough cue still brings them back.

Retrieval is hybrid: cosine similarity over embeddings, blended with keyword overlap, weighted by how well the memory is currently retained. Bring your own embedding model, or use the built-in pure-Python fallback so it keeps working with no API key and no network.

Mood is not decoration. High fatigue shrinks the step budget; high frustration triggers delegation to sub-agents. Persona, relationship, and mood shape the prompt on every turn — and all three persist across sessions.

Every turn writes a structured execution trace you can actually read: /trace for the timeline, /trace json for the whole tree.

4,700 lines of Python, no framework, no vector database, no build step. Copy it anywhere and run it.

35 built-in tools. 43 slash commands.

A few of the ones worth knowing on day one:

Full reference, architecture notes, and every environment variable: README_Polaris_1_1_6.md

Every decision made by Polaris is guided by five core principles.

Truth before fluency. Never pretend certainty. If Polaris is unsure, it says so.

Verify before acting. Observe first. Verify assumptions. Then act.

Preserve user intent. Always optimize for what the user actually wants.

Learn, but never assume. Adapt gradually without drawing unsupported conclusions.

Grow through experience. Every interaction should improve future performance.

Polaris can write files and run shell commands. It ships with a Python sandbox, a destructive-command guard, file checkpoints with /undo, and three permission modes — but none of that makes it safe to point at anything you cannot afford to lose.

• Review generated code before running it.
• Apply the principle of least privilege.
• Run it in a container or under a dedicated low-privilege account for real isolation.
• Do not use it in safety-critical, medical, legal, or financial settings without independent verification.
• Keep backups before letting any AI system modify your files.

The shell guard stops accidents in auto mode, not a determined attacker.

Shipped — Persona Engine · Mood Engine · Long-Term Memory · Vector memory on an Ebbinghaus forgetting curve · Reflection · Workspace Awareness · MCP Support · Plugin System · Productivity Engine · Thought Engine · Experience Model · Relationship State · Reason Engine · Trace Engine · Context Providers · Snapshot Manager

Next — Internationalization · Persona Engine v2 · Workflow graph · Web UI · Voice interaction

Active development. Features, APIs, and internal architecture may change between releases.

Contributions of all kinds are welcome — bug reports, documentation, ideas, or code. Open an issue or a pull request.

On how this was built. Polaris is developed with AI coding tools — Codex and Claude Code. I set the direction, make the architectural calls, and review what goes in; the agents do a large share of the typing. The commit history shows who did what, and commits made with Claude Code carry a Co-Authored-By trailer.

Saying so costs nothing and seems more useful than letting anyone guess.

Polaris is an experimental open-source AI agent intended for research, learning, and software development. Despite its safety mechanisms it can still generate inaccurate information, produce incorrect code, or perform unintended actions. You are responsible for reviewing everything it generates before applying it anywhere that matters. The maintainers are not liable for any direct or indirect damages resulting from its use.

MIT

The future of AI is not simply about answering questions. It is about building systems that can remember, reflect, learn, and develop a consistent identity.

Polaris isn't trying to become the biggest AI agent. It's trying to become one of the most trustworthy ones.

Technology should make AI more capable. Character should make AI more trustworthy.