{"id":19484984,"url":"https://github.com/opencog/atomspace-cog","last_synced_at":"2025-06-24T00:32:07.952Z","repository":{"id":37639999,"uuid":"280643949","full_name":"opencog/atomspace-cog","owner":"opencog","description":"Distributed AtomSpace Network client","archived":false,"fork":false,"pushed_at":"2025-02-02T22:33:24.000Z","size":464,"stargazers_count":11,"open_issues_count":1,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-04T00:51:11.470Z","etag":null,"topics":["atomspace","distributed","network","opencog"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opencog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-18T11:38:27.000Z","updated_at":"2025-03-07T15:44:40.000Z","dependencies_parsed_at":"2025-02-02T22:21:47.785Z","dependency_job_id":"7c3499f6-9dd4-4105-b24d-da578bc23f11","html_url":"https://github.com/opencog/atomspace-cog","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/opencog/atomspace-cog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-cog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-cog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-cog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-cog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opencog","download_url":"https://codeload.github.com/opencog/atomspace-cog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-cog/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261582670,"owners_count":23180634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomspace","distributed","network","opencog"],"created_at":"2024-11-10T20:24:59.236Z","updated_at":"2025-06-24T00:32:07.929Z","avatar_url":"https://github.com/opencog.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nAtomSpace CogStorage Client\n===========================\n\u003c!--\n[![CircleCI](https://circleci.com/gh/opencog/atomspace-cog.svg?style=svg)](https://circleci.com/gh/opencog/atomspace-cog)\n--\u003e\n\nThe code in this git repo allows an AtomSpace to communicate with\nother AtomSpaces by having them all connect to a common CogServer.\nThe CogServer itself also provides an AtomSpace, which all clients\ninteract with, in common.  In ASCII-art:\n```\n +-------------+\n |  CogServer  |\n |    with     |  \u003c-----internet------\u003e Remote AtomSpace A\n |  AtomSpace  |  \u003c---+\n +-------------+      |\n                      +-- internet ---\u003e Remote AtomSpace B\n\n```\n\nHere, AtomSpace A can load/store Atoms (and Values) to the CogServer,\nas can AtomSpace B, and so these two can share AtomSpace contents\nhowever desired.\n\nThis provides a simple, straight-forward backend for networking\ntogether multiple AtomSpaces so that they can share data. This\nbackend, together with the file-based (RocksDB-based) backend\nat [atomspace-rocks](https://github.com/opencog/atomspace-rocks)\nis meant to provide a building-block out of which more complex\ndistributed and/or decentralized AtomSpaces can be built.\n\nThis really is decentralized: you can talk to multiple servers at once.\nThere is no particular limit, other than that of bandwidth,\nresponse-time, etc.  In ASCII-art:\n\n```\n +-----------+\n |           |  \u003c---internet--\u003e My AtomSpace\n |  Server A |                      ^  ^\n |           |        +-------------+  |\n +-----------+        v                v\n                 +----------+   +-----------+\n                 |          |   |           |\n                 | Server B |   |  Server C |\n                 |          |   |           |\n                 +----------+   +-----------+\n```\n\nHere's yet another diagram, reflecting the actual usage in the\n[LinkGrammar AtomSpace dictionary](https://github.com/opencog/link-grammar/tree/master/link-grammar/dict-atomese).\nStacked boxes represent shared-libraries, with shared-library calls going\ndownwards. Note that AtomSpaces start out empty, so the data has to come\n\"from somewhere\". In this case, the data comes from another AtomSpace, running\nremotely (in the demo, its in a Docker container).  That AtomSpace in turn\nloads its data from a\n[RocksStorageNode](https://github.com/opencog/opencog-rocks), which uses\n[RocksDB](https://rocksdb.org) to work with the local disk drive.\nThe network connection is provided by a\n[CogServer](https://github.com/opencog/cogserver) to\n[CogStorageNode](https://github.com/opencog/opencog-cog) pairing.\n```\n                                            +----------------+\n                                            |  Link Grammar  |\n                                            |    parser      |\n                                            +----------------+\n                                            |   AtomSpace    |\n    +-------------+                         +----------------+\n    |             |                         |                |\n    |  Cogserver  | \u003c\u003c==== Internet ====\u003e\u003e  | CogStorageNode |\n    |             |                         |                |\n    +-------------+                         +----------------+\n    |  AtomSpace  |\n    +-------------+\n    |    Rocks    |\n    | StorageNode |\n    +-------------+\n    |   RocksDB   |\n    +-------------+\n    | disk drive  |\n    +-------------+\n```\n\n\nExample Usage\n-------------\nWell, see the examples directory for details. But, in brief:\n\n* Start the CogServer at \"example.com\":\n```\n$ guile\nscheme@(guile-user)\u003e (use-modules (opencog))\nscheme@(guile-user)\u003e (use-modules (opencog cogserver))\nscheme@(guile-user)\u003e (start-cogserver)\n$1 = \"Started CogServer\"\nscheme@(guile-user)\u003e Listening on port 17001\n```\nThen create some atoms (if desired)\n\n* On the client machine:\n```\n$ guile\nscheme@(guile-user)\u003e (use-modules (opencog))\nscheme@(guile-user)\u003e (use-modules (opencog persist))\nscheme@(guile-user)\u003e (use-modules (opencog persist-cog))\nscheme@(guile-user)\u003e (cogserver-open \"cog://example.com/\")\nscheme@(guile-user)\u003e (load-atomspace)\n```\n\nThat's it! You've copied the entire AtomSpace from the server to\nthe client!  Of course, copying everything is generally a bad idea\n(well, for example, its slow, when the atomspace is large). More\ngranular load and store is possible; see the\n[examples directory](examples) for details.\n\nStatus\n------\nThis is **Version 1.1.0**. All 26 (13+13) unit tests consistently\npass. (*) (There are occasional crashes during shutdown, in the\nshared-library dtor, after the unit tests have passed. See\n[cogutil issue #247](https://github.com/opencog/cogutil/issues/247)\nfor details. Tracked locally as\n[atomspace-cog issue #2](https://github.com/opencog/atomspace-cog/issues/2).)\n\nPerformance looks good. Two of the unit tests take about 20 seconds\neach to run; two more take a few minutes.  This is intentional,\nthey are pounding the server with large datasets.\n\nThis is a \"stable\" version. There are no known bugs at this time.\nIt is being used in \"production\" environments, successfully transferring\ngigabytes of data around.\n\nThere is one missing feature, but no one uses it (yet): support for\nmultiple atomspaces (aka frames) is missing. Work on adding this was\nstarted but is low priority.  One unit test works. See the `cog-simple`\ndirectory.\n\nDesign\n------\nThere are actually two implementations in this repo. One that is\n\"simple\", and one that is multi-threaded and concurrent (and so\nshould have a higher throughput). Both \"do the same thing\",\nfunctionally, but differ in network usage, concurrency, etc.\n\n### The Simple Backend\nThis can be found in the [opencog/persist/cog-simple](opencog/persist/cog-simple)\ndirectory.  The grand-total size of this implementation is less than 500\nlines of code. Seriously! This is really a very simple system!  Take a\nlook at [CogSimpleStorage.h](opencog/persist/cog-simple/CogSimpleStorage.h)\nfirst, and then take a look at\n[CogSimpleIO.cc](opencog/persist/cog-simple/CogSimpleIO.cc)\nwhich does all of the data transfer to/from the cogserver. Finally,\n[CogSimpleStorage.cc](opencog/persist/cog-simple/CogSimpleStorage.cc)\nprovides init and socket I/O.\n\nThis backend can be accessed via:\n```\nscheme\u003e (use-modules (opencog persist-cog-simple))\nscheme\u003e (define cssn (CogSimpleStorageNode \"cog://example.com/\"))\nscheme\u003e (cog-open cssn)\n```\n\n### The Production Backend\nThis backend opens four sockets to the cogserver, and handles requests\nasynchronously. In other words, requests might be handled out-of-order.\nIf there is some critical code segment that can't tolerate this, use the\n`(barrier)` call. It will flush the network buffers, and force a\nserialization barrier at the remote end. The `(barrier)` is a 'fence'\nand not a synchronization chekpoint: it ensures that all reads/writes\nbefore the barrier are completed before any that come after are started.\n\nUsage is much like before:\n```\nscheme\u003e (use-modules (opencog persist-cog))\nscheme\u003e (define csn (CogStorageNode \"cog://example.com/\"))\nscheme\u003e (cog-open csn)\n```\n\nURL's\n-----\nSupported URL's include:\n* `cog://example.com/` -- standard internet hostname\n* `cog://1.2.3.4/` -- standard dotted IPv4 address\n* `cog://example.com:17001` -- specify the port of the cogserver.\n\nSee\n[proxying](https://github.com/opencog/atomspace/tree/master/opencog/persist/proxy)\nfor details about how the cogserver can pass on I/O requests to other\nstorage nodes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencog%2Fatomspace-cog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencog%2Fatomspace-cog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencog%2Fatomspace-cog/lists"}