alexein-cli 0.3.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.
Files changed (40) hide show
  1. alexein_cli/__init__.py +127 -0
  2. alexein_cli/_version.py +1 -0
  3. alexein_cli/create.py +178 -0
  4. alexein_cli/create_crewai.py +138 -0
  5. alexein_cli/crews.py +120 -0
  6. alexein_cli/doctor.py +182 -0
  7. alexein_cli/env.py +125 -0
  8. alexein_cli/project.py +312 -0
  9. alexein_cli/render.py +40 -0
  10. alexein_cli/scaffold.py +369 -0
  11. alexein_cli/stop.py +12 -0
  12. alexein_cli/templates/crewai/memory.py.tmpl +55 -0
  13. alexein_cli/templates/crewai/project/README.md.tmpl +29 -0
  14. alexein_cli/templates/crewai/project/agents.yaml.tmpl +8 -0
  15. alexein_cli/templates/crewai/project/crew.py.tmpl +43 -0
  16. alexein_cli/templates/crewai/project/env.example.tmpl +8 -0
  17. alexein_cli/templates/crewai/project/gitignore.tmpl +3 -0
  18. alexein_cli/templates/crewai/project/main.py.tmpl +36 -0
  19. alexein_cli/templates/crewai/project/pyproject.toml.tmpl +20 -0
  20. alexein_cli/templates/crewai/project/tasks.yaml.tmpl +6 -0
  21. alexein_cli/templates/langgraph/memory.py.tmpl +45 -0
  22. alexein_cli/templates/langgraph/project/README.md.tmpl +31 -0
  23. alexein_cli/templates/langgraph/project/chat.py.tmpl +46 -0
  24. alexein_cli/templates/langgraph/project/env.example.tmpl +8 -0
  25. alexein_cli/templates/langgraph/project/graph.py.tmpl +61 -0
  26. alexein_cli/templates/langgraph/project/langgraph.json.tmpl +7 -0
  27. alexein_cli/templates/openai_agents/memory.py.tmpl +47 -0
  28. alexein_cli/templates/openai_agents/project/README.md.tmpl +25 -0
  29. alexein_cli/templates/openai_agents/project/agent.py.tmpl +43 -0
  30. alexein_cli/templates/openai_agents/project/chat.py.tmpl +38 -0
  31. alexein_cli/templates/openai_agents/project/env.example.tmpl +6 -0
  32. alexein_cli/templates/project/gitignore.tmpl +6 -0
  33. alexein_cli/templates/project/pyproject.toml.tmpl +14 -0
  34. alexein_cli/ui.py +75 -0
  35. alexein_cli/wiring.py +61 -0
  36. alexein_cli-0.3.0.dist-info/METADATA +208 -0
  37. alexein_cli-0.3.0.dist-info/RECORD +40 -0
  38. alexein_cli-0.3.0.dist-info/WHEEL +4 -0
  39. alexein_cli-0.3.0.dist-info/entry_points.txt +2 -0
  40. alexein_cli-0.3.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,46 @@
1
+ """Talk to the agent in a terminal, as one of your users:
2
+
3
+ uv run -m {package}.chat --user dana
4
+
5
+ Each run is a new conversation; what the agent remembers from the last one is memory's.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import uuid
12
+
13
+ from dotenv import load_dotenv
14
+ from langchain_core.messages import AnyMessage, HumanMessage
15
+
16
+ load_dotenv()
17
+
18
+ # After .env: the model and memory read their keys from it.
19
+ from {package}.graph import graph # noqa: E402
20
+
21
+
22
+ def main() -> None:
23
+ parser = argparse.ArgumentParser(description="Talk to the agent.")
24
+ parser.add_argument("--user", default="dana", help="whose memory the agent reads")
25
+ user = parser.parse_args().user
26
+ config = {"configurable": {"thread_id": uuid.uuid4().hex}}
27
+ print(f"Talking as {user}. An empty line, or Ctrl-D, ends the conversation.")
28
+ messages: list[AnyMessage] = []
29
+ while True:
30
+ try:
31
+ line = input("you> ").strip()
32
+ except EOFError: # Ctrl-D, or the end of piped input
33
+ print()
34
+ break
35
+ if not line:
36
+ break
37
+ messages.append(HumanMessage(line))
38
+ out = graph.invoke(
39
+ {"messages": messages}, config=config, context={"user_id": user}
40
+ )
41
+ messages = out["messages"]
42
+ print(f"agent> {messages[-1].text}")
43
+
44
+
45
+ if __name__ == "__main__":
46
+ main()
@@ -0,0 +1,8 @@
1
+ # The model the agent talks with, as LangChain's init_chat_model names it.
2
+ MODEL={model}
3
+ # >>> provider_key
4
+ {provider_key}=
5
+ # <<< provider_key
6
+ # Alexein: make a key in the console, under API keys.
7
+ ALEXEIN_API_KEY=
8
+ # ALEXEIN_API_URL=https://api.alexein.ai
@@ -0,0 +1,61 @@
1
+ """The agent: a model that remembers the people it talks to.
2
+
3
+ Made by `alexein-cli create langgraph`. Memory comes from `memory.py`, beside it:
4
+ `memory.recall` looks up what memory holds before the model answers, `memory.remember`
5
+ saves the turn after it, and the model can search memory itself with `memory.tools()`.
6
+
7
+ Whose memory a run reads is the `user_id` in its context, which your code sets:
8
+
9
+ graph.invoke(inputs, context={"user_id": "dana"})
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import os
15
+ from functools import cache
16
+ from typing import Any
17
+
18
+ from langchain.chat_models import init_chat_model
19
+ from langchain_core.messages import SystemMessage
20
+ from langgraph.graph import END, START, StateGraph
21
+ from langgraph.prebuilt import ToolNode, tools_condition
22
+
23
+ from {package}.memory import MemoryContext, MemoryState, memory
24
+
25
+ # `memory.remember` saves every turn, so the model is only given the tools that read.
26
+ TOOLS = memory.tools()
27
+
28
+ SYSTEM = (
29
+ "You are a helpful assistant. You remember the people you talk to across "
30
+ "conversations; use what you remember where it helps, and never invent it."
31
+ )
32
+
33
+
34
+ @cache
35
+ def _model() -> Any:
36
+ """The chat model `MODEL` in .env names, made on first use."""
37
+ return init_chat_model(os.environ.get("MODEL", "{model}")).bind_tools(TOOLS)
38
+
39
+
40
+ def agent(state: MemoryState) -> dict[str, Any]:
41
+ system = SYSTEM
42
+ remembered = memory.prompt(state)
43
+ if remembered:
44
+ system += "\n\n" + remembered
45
+ reply = _model().invoke([SystemMessage(system), *state["messages"]])
46
+ return {"messages": [reply]}
47
+
48
+
49
+ builder = StateGraph(MemoryState, context_schema=MemoryContext)
50
+ builder.add_node("recall", memory.recall)
51
+ builder.add_node("agent", agent)
52
+ builder.add_node("tools", ToolNode(TOOLS))
53
+ builder.add_node("remember", memory.remember)
54
+ builder.add_edge(START, "recall")
55
+ builder.add_edge("recall", "agent")
56
+ builder.add_conditional_edges(
57
+ "agent", tools_condition, {"tools": "tools", "__end__": "remember"}
58
+ )
59
+ builder.add_edge("tools", "agent")
60
+ builder.add_edge("remember", END)
61
+ graph = builder.compile()
@@ -0,0 +1,7 @@
1
+ {
2
+ "dependencies": ["."],
3
+ "graphs": {
4
+ "agent": "./src/{package}/graph.py:graph"
5
+ },
6
+ "env": ".env"
7
+ }
@@ -0,0 +1,47 @@
1
+ """Long-term memory for your agents, from Alexein.
2
+
3
+ Generated by `alexein-cli init openai-agents` (alexein-cli {version}); yours to edit.
4
+ The settings are here; recall, remember and the tools come from `alexein.openai_agents`
5
+ (https://docs.alexein.ai/integrations/openai-agents).
6
+
7
+ agent = Agent(name="Assistant", tools=memory.tools()) # write=True: and save
8
+ result = await Runner.run(
9
+ agent,
10
+ message,
11
+ context=MemoryContext(user_id="dana", session_id="conv-7"),
12
+ run_config=RunConfig(call_model_input_filter=memory.recall),
13
+ )
14
+ await memory.remember(result) # for run_streamed, once its events are consumed
15
+
16
+ `memory.recall` adds what memory holds to the instructions, never to your history.
17
+ Whose memory is read is your code's choice, never the model's: any context with a
18
+ `user_id` will do. The key is ALEXEIN_API_KEY and the address ALEXEIN_API_URL, read on
19
+ the first call: importing needs neither.
20
+ """
21
+
22
+ from alexein.openai_agents import AlexeinMemory, MemoryContext
23
+
24
+ __all__ = ["MemoryContext", "memory"]
25
+
26
+ # True skips search's relevance check: free and quicker, a little less precise. Use it
27
+ # where a reply cannot wait, like a voice agent's turn.
28
+ FAST = {fast}
29
+
30
+ # False keeps your agent running while memory is down: a turn goes on without its
31
+ # memory, a save is skipped, a tool tells the model memory is unavailable, and a
32
+ # warning is logged on the `alexein` logger. True raises instead. A wrong key raises
33
+ # either way: that is a mistake to fix.
34
+ STRICT = False
35
+
36
+ # How much of what memory holds goes into the instructions, in characters.
37
+ MAX_CHARS = 4000
38
+
39
+ # Seconds each attempt at a call may take; a call is tried up to three times.
40
+ TIMEOUT = 10.0
41
+
42
+ memory = AlexeinMemory(
43
+ fast=FAST,
44
+ max_chars=MAX_CHARS,
45
+ strict=STRICT,
46
+ timeout=TIMEOUT,
47
+ )
@@ -0,0 +1,25 @@
1
+ # {name}
2
+
3
+ An OpenAI Agents SDK agent that remembers the people it talks to, with
4
+ [Alexein](https://alexein.ai). Made by `alexein-cli create openai-agents`.
5
+
6
+ ## Run it
7
+
8
+ 1. Fill in `.env`: `ALEXEIN_API_KEY` (the console, under API keys) and `OPENAI_API_KEY`.
9
+ 2. Talk to it in a terminal, as one of your users:
10
+
11
+ ```bash
12
+ uv run -m {package}.chat --user dana
13
+ ```
14
+
15
+ 3. `uvx alexein-cli doctor` checks the setup.
16
+
17
+ ## What is where
18
+
19
+ - `src/{package}/agent.py` - the agent: memory is wired in here.
20
+ - `src/{package}/memory.py` - memory's settings and wiring, written by
21
+ `alexein-cli init openai-agents`; recall, remember and the tools come from
22
+ `alexein.openai_agents`. Yours to edit.
23
+ - `src/{package}/chat.py` - the terminal chat.
24
+
25
+ Whose memory a run reads is the `user_id` in its context, set by your code and never by the model.
@@ -0,0 +1,43 @@
1
+ """The agent: a model that remembers the people it talks to.
2
+
3
+ Made by `alexein-cli create openai-agents`. Memory comes from `memory.py`, beside it:
4
+ `memory.recall` looks up what memory holds before the model answers, `memory.remember`
5
+ saves the turn after it, and the model can search memory itself with `memory.tools()`.
6
+
7
+ Whose memory a run reads is the `user_id` in its context, which your code sets:
8
+
9
+ await reply("Where do I live?", MemoryContext(user_id="dana"))
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import os
15
+
16
+ from agents import Agent, RunConfig, Runner, TResponseInputItem
17
+ from agents.result import RunResult
18
+
19
+ from {package}.memory import MemoryContext, memory
20
+
21
+ agent = Agent[MemoryContext](
22
+ name="Assistant",
23
+ instructions=(
24
+ "You are a helpful assistant. You remember the people you talk to across "
25
+ "conversations; use what you remember where it helps, and never invent it."
26
+ ),
27
+ # `MODEL` in .env; empty, the OpenAI Agents SDK's default.
28
+ model=os.environ.get("MODEL") or None,
29
+ # `memory.remember` saves every turn, so the model gets only the tools that read.
30
+ tools=memory.tools(),
31
+ )
32
+
33
+ # Memory goes into the instructions of every model call, looked up once a turn.
34
+ RUN_CONFIG = RunConfig(call_model_input_filter=memory.recall)
35
+
36
+
37
+ async def reply(
38
+ said: str | list[TResponseInputItem], context: MemoryContext
39
+ ) -> RunResult:
40
+ """One turn. `said` is the user's message, or the conversation ending with it."""
41
+ result = await Runner.run(agent, said, context=context, run_config=RUN_CONFIG)
42
+ await memory.remember(result)
43
+ return result
@@ -0,0 +1,38 @@
1
+ """Talk to the agent in a terminal, as one of your users:
2
+
3
+ uv run -m {package}.chat --user dana
4
+
5
+ Each run is a new conversation; what the agent remembers from the last one is memory's.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import asyncio
12
+ import uuid
13
+
14
+ from agents import TResponseInputItem
15
+ from dotenv import load_dotenv
16
+
17
+ load_dotenv()
18
+
19
+ # After .env: the model and memory read their keys from it.
20
+ from {package}.agent import reply # noqa: E402
21
+ from {package}.memory import MemoryContext # noqa: E402
22
+
23
+
24
+ async def main() -> None:
25
+ parser = argparse.ArgumentParser(description="Talk to the agent.")
26
+ parser.add_argument("--user", default="dana", help="whose memory the agent reads")
27
+ user = parser.parse_args().user
28
+ context = MemoryContext(user_id=user, session_id=uuid.uuid4().hex)
29
+ print(f"Talking as {user}. An empty line ends the conversation.")
30
+ history: list[TResponseInputItem] = []
31
+ while line := input("you> ").strip():
32
+ result = await reply([*history, {"role": "user", "content": line}], context)
33
+ history = result.to_input_list()
34
+ print(f"agent> {result.final_output}")
35
+
36
+
37
+ if __name__ == "__main__":
38
+ asyncio.run(main())
@@ -0,0 +1,6 @@
1
+ # The model the agent talks with; empty, the OpenAI Agents SDK's default.
2
+ MODEL={model}
3
+ OPENAI_API_KEY=
4
+ # Alexein: make a key in the console, under API keys.
5
+ ALEXEIN_API_KEY=
6
+ # ALEXEIN_API_URL=https://api.alexein.ai
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ .env
3
+ __pycache__/
4
+ # >>> langgraph
5
+ .langgraph_api/
6
+ # <<< langgraph
@@ -0,0 +1,14 @@
1
+ [project]
2
+ name = "{name}"
3
+ version = "0.1.0"
4
+ description = "{description}"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ dependencies = []
8
+
9
+ [build-system]
10
+ requires = ["hatchling"]
11
+ build-backend = "hatchling.build"
12
+
13
+ [tool.hatch.build.targets.wheel]
14
+ packages = ["src/{package}"]
alexein_cli/ui.py ADDED
@@ -0,0 +1,75 @@
1
+ """How the CLI talks to the person running it: lines of output, and questions when there is
2
+ someone at a terminal to answer them. A test hands in a `Console` with answers ready; a script
3
+ or CI gets one that asks nothing and takes every default.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import getpass
9
+ import sys
10
+ from collections.abc import Callable, Sequence
11
+ from dataclasses import dataclass, field
12
+
13
+
14
+ @dataclass
15
+ class Console:
16
+ """`interactive` is whether questions can be asked. `answers` stand in for typed replies
17
+ in tests, in order; `said` keeps every line printed, for the same."""
18
+
19
+ interactive: bool = False
20
+ yes: bool = False
21
+ answers: list[str] = field(default_factory=list[str])
22
+ said: list[str] = field(default_factory=list[str])
23
+ out: Callable[[str], None] | None = None
24
+
25
+ @classmethod
26
+ def for_terminal(cls, *, yes: bool) -> Console:
27
+ return cls(interactive=sys.stdin.isatty() and not yes, yes=yes)
28
+
29
+ def line(self, text: str = "") -> None:
30
+ self.said.append(text)
31
+ (self.out or _print)(text)
32
+
33
+ def step(self, verb: str, what: str) -> None:
34
+ self.line(f" {verb:<9}{what}")
35
+
36
+ def fail(self, why: str) -> None:
37
+ self.line(f"alexein-cli: {why}")
38
+
39
+ def _reply(self, prompt: str, *, secret: bool) -> str:
40
+ if self.answers:
41
+ reply = self.answers.pop(0)
42
+ self.said.append(f"{prompt}{'***' if secret and reply else reply}")
43
+ return reply
44
+ if secret:
45
+ return getpass.getpass(prompt)
46
+ return input(prompt)
47
+
48
+ def confirm(self, question: str) -> bool:
49
+ """Yes with `--yes`; asked at a terminal; no otherwise."""
50
+ if self.yes:
51
+ return True
52
+ if not self.interactive:
53
+ return False
54
+ return self._reply(f" {question} [y/N] ", secret=False).strip().lower() in ("y", "yes")
55
+
56
+ def secret(self, question: str) -> str:
57
+ """A key, typed without echo; empty when skipped or when nobody can answer."""
58
+ if not self.interactive:
59
+ return ""
60
+ return self._reply(f" {question} ", secret=True).strip()
61
+
62
+ def choose(self, question: str, options: Sequence[str]) -> str | None:
63
+ """One of `options` by number or name; None when nobody can answer."""
64
+ if not self.interactive:
65
+ return None
66
+ for n, option in enumerate(options, 1):
67
+ self.line(f" {n}. {option}")
68
+ reply = self._reply(f" {question} ", secret=False).strip()
69
+ if reply.isdigit() and 1 <= int(reply) <= len(options):
70
+ return options[int(reply) - 1]
71
+ return reply if reply in options else None
72
+
73
+
74
+ def _print(text: str) -> None:
75
+ print(text, flush=True)
alexein_cli/wiring.py ADDED
@@ -0,0 +1,61 @@
1
+ """What `init` tells the developer to wire in once the file is written: the import, and the
2
+ lines that use it, for LangGraph and the OpenAI Agents SDK (CrewAI's are `crews.py`'s). Text
3
+ only; nothing here touches the project.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from alexein_cli import env
9
+
10
+
11
+ def next_steps(module: str, framework: str) -> str:
12
+ if framework == "openai-agents":
13
+ return _openai_agents(module)
14
+ return "\n".join(
15
+ [
16
+ " Wire it in, where you build your graph:",
17
+ "",
18
+ f" from {module} import MemoryContext, MemoryState, memory",
19
+ "",
20
+ " builder = StateGraph(MemoryState, context_schema=MemoryContext)",
21
+ ' builder.add_node("recall", memory.recall)',
22
+ ' builder.add_node("remember", memory.remember)',
23
+ ' builder.add_edge(START, "recall")',
24
+ ' builder.add_edge("recall", "agent") # your model node: memory.prompt(state)',
25
+ ' builder.add_edge("agent", "remember") # goes in its system prompt',
26
+ "",
27
+ " # or let the model look things up itself (write=True: and save)",
28
+ " create_agent(model, tools=memory.tools(), context_schema=MemoryContext)",
29
+ "",
30
+ " Run with the app user's id; the model never chooses it:",
31
+ "",
32
+ ' graph.invoke(inputs, config={"configurable": {"thread_id": "t-1"}},',
33
+ ' context={"user_id": "dana"})',
34
+ "",
35
+ f" The key is {env.KEY} in .env. `langgraph dev` loads .env when",
36
+ ' langgraph.json has "env": ".env"; a plain script loads it itself.',
37
+ " `alexein-cli doctor` checks it all.",
38
+ ]
39
+ )
40
+
41
+
42
+ def _openai_agents(module: str) -> str:
43
+ return "\n".join(
44
+ [
45
+ " Wire it in, where you run your agent:",
46
+ "",
47
+ f" from {module} import MemoryContext, memory",
48
+ "",
49
+ ' agent = Agent(name="Assistant", tools=memory.tools()) # write=True: and save',
50
+ " result = await Runner.run(",
51
+ " agent,",
52
+ " message,",
53
+ ' context=MemoryContext(user_id="dana"), # the app user; never the model',
54
+ " run_config=RunConfig(call_model_input_filter=memory.recall),",
55
+ " )",
56
+ " await memory.remember(result)",
57
+ "",
58
+ f" The key is {env.KEY} in .env; load it (python-dotenv) before the",
59
+ " first run. `alexein-cli doctor` checks it all.",
60
+ ]
61
+ )
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.5
2
+ Name: alexein-cli
3
+ Version: 0.3.0
4
+ Summary: Add memory from Alexein to a LangGraph project, a CrewAI crew or an OpenAI Agents SDK agent, as a short file you own: uvx alexein-cli init langgraph | crewai | openai-agents.
5
+ Project-URL: Homepage, https://alexein.ai
6
+ Project-URL: Documentation, https://docs.alexein.ai/integrations/langgraph
7
+ Project-URL: Repository, https://github.com/Alexein-AI/sdk
8
+ Project-URL: Changelog, https://github.com/Alexein-AI/sdk/blob/main/integrations/cli-python/CHANGELOG.md
9
+ Author: Alexein AI
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agents,cli,crewai,langgraph,llm,memory,openai-agents
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: alexein>=0.3
24
+ Description-Content-Type: text/markdown
25
+
26
+ # alexein-cli
27
+
28
+ Memory from [Alexein](https://alexein.ai) in a LangGraph project, a CrewAI crew or an OpenAI
29
+ Agents SDK agent, as a short file you own: one command writes `memory.py` - your settings and one
30
+ configured `AlexeinMemory`, wired from the [`alexein`](https://docs.alexein.ai/sdks/python)
31
+ client's integration for your framework - and adds `alexein[<framework>]` to your project.
32
+
33
+ ```bash
34
+ uvx alexein-cli init langgraph # a LangGraph project you have
35
+ uvx alexein-cli init crewai # a crew you have
36
+ uvx alexein-cli init openai-agents # an OpenAI Agents SDK project you have
37
+ uvx alexein-cli create langgraph my-agent # a new one, with memory wired in
38
+ uvx alexein-cli create crewai my-crew
39
+ uvx alexein-cli create openai-agents my-agent
40
+ uvx alexein-cli doctor # is it all set up?
41
+ ```
42
+
43
+ The file is yours: edit the settings, rename things, move it. What it imports - recall, saving,
44
+ the tools, failing open - comes from `alexein.langgraph`, `alexein.openai_agents` or
45
+ `alexein.crewai`, and an upgrade of `alexein` reaches it. Importing it needs no key: the client
46
+ is made on the first call to memory, from `ALEXEIN_API_KEY` and `ALEXEIN_API_URL`.
47
+
48
+ ## `init`
49
+
50
+ Before it writes anything, `init` checks that it is in a Python project, that the project uses
51
+ the framework (it asks before going on in one that does not; `--yes` goes on without asking),
52
+ that what is installed is new enough (LangGraph 1.2, LangChain 1.0, the OpenAI Agents SDK 0.24,
53
+ CrewAI 1.15), and where the file goes: beside the graph `langgraph.json` names (asking when there
54
+ are several, or `--graph NAME`), beside the file that builds your `Agent`, or beside your crew.
55
+ Any of these can stop it, and then nothing has changed. An existing `memory.py` is replaced only
56
+ with `--force`.
57
+
58
+ Then it writes `memory.py`, adds `alexein[langgraph]>=0.3` (or `[openai-agents]`, `[crewai]`)
59
+ where the project does not depend on it with that extra yet - with the project's own tool: uv,
60
+ poetry, pdm, or a line in `requirements.txt` - and sets up the key: `--key tm_...`, or asked for
61
+ at a terminal. Enter skips it, and an empty `ALEXEIN_API_KEY=` waits in `.env`. A key it is given
62
+ is checked, and a key that only reads is called out.
63
+
64
+ | Flag | What it does |
65
+ | ---------------------------- | ------------------------------------------------------------ |
66
+ | `--fast` | `FAST = True`: searches skip the relevance check, free and quicker |
67
+ | `--key`, `--base-url` | the key and memory's address, written into `.env` |
68
+ | `--skip-key` | do not ask for a key |
69
+ | `--dir`, `--file`, `--graph` | where the file goes, and what it is called |
70
+ | `--force` | replace a file already there |
71
+ | `--no-install` | print the install command instead of running it |
72
+ | `--dry-run` | make every check, say what would happen, change nothing |
73
+ | `--yes` | ask nothing |
74
+
75
+ Every file holds the same four settings, at the top:
76
+
77
+ | Setting | Default | What it does |
78
+ | ----------- | ------- | ------------------------------------------------------------------- |
79
+ | `FAST` | `False` | `True` answers sooner and free, a little less precisely |
80
+ | `STRICT` | `False` | `True` raises when memory is down, where by default a turn goes on without it |
81
+ | `MAX_CHARS` | `4000` | how much of what memory holds goes into a prompt |
82
+ | `TIMEOUT` | `10.0` | seconds each attempt at a call may take |
83
+
84
+ A wrong key raises whatever `STRICT` says: that is a mistake to fix, not an outage to ride out.
85
+ Memory being down is logged on the `alexein` logger.
86
+
87
+ ### LangGraph
88
+
89
+ `init langgraph` writes `memory`, with `MemoryState` and `MemoryContext`:
90
+
91
+ ```python
92
+ from app.memory import MemoryContext, MemoryState, memory
93
+
94
+ builder = StateGraph(MemoryState, context_schema=MemoryContext)
95
+ builder.add_node("recall", memory.recall) # what memory holds, into state["memory"]
96
+ builder.add_node("agent", agent) # yours: memory.prompt(state) in its prompt
97
+ builder.add_node("remember", memory.remember) # save the turn
98
+ builder.add_edge(START, "recall")
99
+ builder.add_edge("recall", "agent")
100
+ builder.add_edge("agent", "remember")
101
+ graph = builder.compile()
102
+
103
+ graph.invoke(
104
+ {"messages": [HumanMessage("Where do I live?")]},
105
+ config={"configurable": {"thread_id": "t-1"}},
106
+ context={"user_id": "dana"},
107
+ )
108
+ ```
109
+
110
+ Or give the model tools to call when it decides to:
111
+ `create_agent(model, tools=memory.tools(), context_schema=MemoryContext)` offers `memory_search`
112
+ and `memory_open`; `memory.tools(write=True)` adds `memory_add`. The nodes and tools run under
113
+ `invoke` and `ainvoke`; `memory.arecall` and `memory.aremember` are the nodes' async
114
+ counterparts.
115
+
116
+ Whose memory is read comes from the run's `context`, never from the model. A LangGraph thread is
117
+ a memory session.
118
+
119
+ ### The OpenAI Agents SDK
120
+
121
+ `init openai-agents` writes `memory`, with `MemoryContext`, beside the file that builds your
122
+ `Agent` (asking when there are several, or `--dir`; with none, into the project's package):
123
+
124
+ ```python
125
+ from app.memory import MemoryContext, memory
126
+
127
+ agent = Agent(name="Assistant", tools=memory.tools())
128
+ result = await Runner.run(
129
+ agent,
130
+ "Where do I live?",
131
+ context=MemoryContext(user_id="dana", session_id="conv-7"),
132
+ run_config=RunConfig(call_model_input_filter=memory.recall),
133
+ )
134
+ await memory.remember(result) # for run_streamed, once its events are consumed
135
+ ```
136
+
137
+ `memory.recall` searches once a turn and adds what it finds to the instructions of every model
138
+ call in the turn, so it is never written into a `Session`, the Conversations API or
139
+ `to_input_list()`. Any context with a `user_id` will do.
140
+
141
+ ### CrewAI
142
+
143
+ `init crewai` writes `alexein_memory` - CrewAI's own memory, kept in Alexein - and `whose`,
144
+ beside a classic crew (`@CrewBase` in `src/<pkg>/crew.py`) or a JSON one (`crew.jsonc`). Flows
145
+ are not supported yet.
146
+
147
+ ```python
148
+ from my_crew.memory import alexein_memory, whose
149
+
150
+
151
+ @CrewBase
152
+ class MyCrew:
153
+ memory = alexein_memory
154
+
155
+ @before_kickoff
156
+ def whose_memory(self, inputs):
157
+ return whose(inputs)
158
+
159
+ @crew
160
+ def crew(self) -> Crew:
161
+ return Crew(agents=self.agents, tasks=self.tasks, memory=self.memory)
162
+
163
+
164
+ MyCrew().crew().kickoff(inputs={"user_id": "dana", "topic": "..."})
165
+ ```
166
+
167
+ A JSON crew points `crew.jsonc` at the same two names:
168
+
169
+ ```jsonc
170
+ "memory": {"python": "memory.alexein_memory"},
171
+ "before_kickoff_callbacks": [{"python": "memory.whose"}]
172
+ ```
173
+
174
+ CrewAI then recalls the user's memory before every task, saves what each task learned, and gives
175
+ every agent its memory tools. Every kickoff names its user in `inputs["user_id"]`; the key is
176
+ checked at kickoff, once per process. `whose` is a function in the file rather than
177
+ `alexein_memory.whose` because CrewAI keeps only module-level callbacks when it restores a
178
+ checkpoint. Without CrewAI's memory: `Agent(..., tools=alexein_memory.tools("dana"))`, and
179
+ `alexein_memory.save_result("dana", output)` after the run.
180
+
181
+ ## `create`
182
+
183
+ `create <framework> <name>` makes a uv project with memory wired in, and `memory.py` as `init`
184
+ writes it:
185
+
186
+ - `create langgraph` - a graph that recalls, searches and remembers, a terminal chat
187
+ (`uv run -m <package>.chat --user dana`, where `<package>` is the name in lower case with `-`
188
+ as `_`), and `langgraph.json` for `uv run langgraph dev`. `--model` names the model by
189
+ `init_chat_model`'s name (default `anthropic:claude-sonnet-5-5`), whose LangChain package it
190
+ adds.
191
+ - `create openai-agents` - an agent and a terminal chat. `--model` names the model (`MODEL` in
192
+ `.env`); without it, the SDK's default.
193
+ - `create crewai` - a classic crew with one assistant agent and `uv run run_crew --user dana
194
+ "..."`. `--model` takes CrewAI's `provider/model` name (default `anthropic/claude-sonnet-5-5`)
195
+ and adds the CrewAI extra that provider needs.
196
+
197
+ It takes `init`'s `--fast` and key flags.
198
+
199
+ ## `doctor`
200
+
201
+ Checks the memory file, that `alexein` is a dependency with the framework's extra, the installed
202
+ versions, that the integration module imports in the project's own `.venv`, `ALEXEIN_API_KEY`
203
+ and `ALEXEIN_API_URL` (in `.env` or the environment), the key (with `memory.me()`, which is free)
204
+ and that `.env` is not committed. Each failure says how to fix it.
205
+
206
+ ## License
207
+
208
+ MIT